universal-dev-standards 6.1.1 → 6.2.0

package/src/core/manifest.js

@@ -389,6 +389,18 @@ function migrateToV340(manifest) {
   };
 }
 
+// 這裡曾有一個 v3.5.0 遷移，把 `integrations` 正規化為工具鍵。**已撤回。**
+//
+// 撤回的理由，是窮舉讀取端之後才看見的：這個欄位有**兩個陣營**，而且大致均衡。
+//   期待檔名  ：hasher.js（{source:i,target:i}）、check.js ×6（join(projectPath, int)、
+//               filter(i => i !== relativePath)）
+//   期待工具鍵：desired-state-calculator、manifest-migrator、update.js:856（getToolFilePath）
+// 把資料正規化成任何一種，就是修好一邊、弄壞另一邊。
+// 全套 3,240 個測試在正規化之後仍然全綠——那只代表**檔名陣營那幾條路徑沒有覆蓋**，不是安全。
+//
+// 正解是不動資料，讓每個讀取端經 `resolveToolKey` / `resolveIntegrationFile` 容忍兩種形狀。
+// 真要正規化，得排在**所有**讀取端都容錯之後，作為獨立一步。（XSPEC-343 R1）
+
 /**
  * Convert a standards array from legacy path format to registry ID format.
  * Entries that already look like IDs (no "/" or ".") are kept as-is.
@@ -601,4 +613,48 @@ export function areSkillsInstalled(manifest) {
  */
 export function areCommandsInstalled(manifest) {
   return manifest.commands?.installed || false;
+}
+
+/**
+ * Placeholder stored in `skills.names` when skills come from the Claude Code
+ * plugin marketplace rather than being copied into the project.
+ */
+export const MARKETPLACE_NAMES_SENTINEL = 'all-via-plugin';
+
+/**
+ * Merge the names actually installed by a run into a manifest name list.
+ *
+ * `skills.names` / `commands.names` used to be written by `init` and by no other
+ * code path, so they froze on the day a project was set up: machine-setup's said
+ * 32 skills across five UDS upgrades while the shipped set grew to 55. Nothing
+ * errored — a name list that is merely *incomplete* reads exactly like a complete
+ * one, and the reconciler read the gap as "these 40 are no longer wanted".
+ * (XSPEC-343 R1/R2)
+ *
+ * Every code path that installs skills or commands must call this. It lives here
+ * rather than in a command module because there are 18 such call sites across
+ * update.js and config.js, and a private copy per module is how the writers drift
+ * apart again.
+ *
+ * It only ever adds. A name recorded by an older UDS version that no longer ships
+ * (machine-setup still lists `methodology-system`, plus five non-skill directories
+ * an old deny-list bug misfiled as skills) stays in the list. Pruning would need
+ * to know the name is absent for *every* agent, and over-reporting is harmless
+ * now that the reconciler derives desired state from the shipped set instead.
+ *
+ * @param {string[]} existing - Current manifest list
+ * @param {Object} installResult - Result from installSkills/CommandsToMultipleAgents
+ * @returns {string[]} Sorted union of existing and newly installed names
+ */
+export function mergeInstalledNames(existing, installResult) {
+  const merged = new Set(existing || []);
+  // Marketplace installs record a sentinel instead of real names; leave it alone.
+  if (merged.has(MARKETPLACE_NAMES_SENTINEL)) return [...merged];
+
+  for (const agentResult of installResult?.installations || []) {
+    for (const name of agentResult?.installed || []) {
+      merged.add(name);
+    }
+  }
+  return [...merged].sort();
 }

package/src/flow/flow-parser.js

@@ -4,7 +4,7 @@
  * 解析 .flow.yaml 內容為 Flow 物件，包含 schema 驗證和預設值填充。
  */
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 const DEFAULT_CONFIG = {
   enforcement: 'suggest',

package/src/flow/gate-loader.js

@@ -4,7 +4,7 @@
  * 載入和解析 .gate.yaml 閘門定義。
  */
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 /**
  * 從 YAML 字串載入 gate 定義。

package/src/i18n/messages.js

@@ -831,6 +831,8 @@ export const messages = {
         fileNotFound: 'File not found',
         couldNotRead: 'Could not read file',
         standardsIndexPresent: 'Standards index present',
+        standardsIndexCount: 'Index declares {count} standards (matches manifest)',
+        standardsIndexCountMismatch: 'Index declares {declared} standards but the manifest has {actual}',
         standardsReferenced: '{count}/{total} standards referenced',
         missingStandardsList: 'Missing: {list}',
         usingMinimalMode: 'Using minimal mode (no standards index)',
@@ -2063,6 +2065,8 @@ export const messages = {
         fileNotFound: '找不到檔案',
         couldNotRead: '無法讀取檔案',
         standardsIndexPresent: '標準索引存在',
+        standardsIndexCount: '索引宣告 {count} 條標準（與 manifest 一致）',
+        standardsIndexCountMismatch: '索引宣告 {declared} 條標準，manifest 實際有 {actual} 條',
         standardsReferenced: '{count}/{total} 項標準已參考',
         missingStandardsList: '缺少：{list}',
         usingMinimalMode: '使用最小模式（無標準索引）',
@@ -3310,6 +3314,8 @@ export const messages = {
         fileNotFound: '文件未找到',
         couldNotRead: '无法读取文件',
         standardsIndexPresent: '标准索引存在',
+        standardsIndexCount: '索引声明 {count} 条标准（与 manifest 一致）',
+        standardsIndexCountMismatch: '索引声明 {declared} 条标准，manifest 实际有 {actual} 条',
         standardsReferenced: '已引用 {count}/{total} 项标准',
         missingStandardsList: '缺失：{list}',
         usingMinimalMode: '使用最小模式（无标准索引）',

package/src/installers/standards-installer.js

@@ -10,6 +10,7 @@ import {
 import { copyStandard } from '../utils/copier.js';
 import { t } from '../i18n/messages.js';
 import { computeFileHash } from '../utils/hasher.js';
+import { MANIFEST_OPTION_BINDINGS } from '../core/constants.js';
 
 // Extension file mappings
 export const EXTENSION_MAPPINGS = {
@@ -89,28 +90,17 @@ export async function installStandards(config, projectPath) {
       }
     }
 
-    // Copy selected options for this standard
+    // Copy selected options for this standard.
+    // The manifest-key → (standard, category) mapping lives in MANIFEST_OPTION_BINDINGS
+    // so the reconciler computes the same desired set this loop installs. It used to
+    // be spelled out inline here and guessed at incorrectly there. (XSPEC-343 R2)
     if (std.options) {
       for (const targetFormat of formatsToUse) {
-        // Git workflow options
-        if (std.id === 'git-workflow') {
-          if (config.standardOptions.workflow) {
-            const copied = await copyOptionFiles(std, 'workflow', config.standardOptions.workflow, targetFormat);
-            results.standards.push(...copied);
-          }
-          if (config.standardOptions.merge_strategy) {
-            const copied = await copyOptionFiles(std, 'merge_strategy', config.standardOptions.merge_strategy, targetFormat);
-            results.standards.push(...copied);
-          }
-        }
-        // Commit message options
-        if (std.id === 'commit-message' && (config.standardOptions.output_language || config.standardOptions.commit_language)) {
-          const copied = await copyOptionFiles(std, 'output_language', config.standardOptions.output_language || config.standardOptions.commit_language, targetFormat);
-          results.standards.push(...copied);
-        }
-        // Testing options
-        if (std.id === 'testing' && config.standardOptions.test_levels) {
-          const copied = await copyOptionFiles(std, 'test_level', config.standardOptions.test_levels, targetFormat);
+        for (const binding of MANIFEST_OPTION_BINDINGS) {
+          if (binding.standardId !== std.id) continue;
+          const key = binding.manifestKeys.find(k => config.standardOptions?.[k] != null);
+          if (!key) continue;
+          const copied = await copyOptionFiles(std, binding.categoryKey, config.standardOptions[key], targetFormat);
           results.standards.push(...copied);
         }
       }

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

@@ -12,7 +12,16 @@ import { join, relative } from 'path';
 import { readManifest } from '../core/manifest.js';
 import { computeFileHash, computeIntegrationBlockHash } from '../utils/hasher.js';
 import { SUPPORTED_AI_TOOLS, UDS_MARKERS } from '../core/constants.js';
-import { getSkillsDirForAgent, getCommandsDirForAgent } from '../config/ai-agent-paths.js';
+import { getSkillsDirForAgent, getCommandsDirForAgent, getCommandFileExtension } from '../config/ai-agent-paths.js';
+import { getSkillsSourceEntryNames, getAvailableCommandNames } from '../utils/skills-installer.js';
+
+/**
+ * Files UDS writes into a skills/commands directory for its own bookkeeping.
+ * They are not skills or commands and must never be diffed as such — the
+ * scanner used to report `.manifest.json` as a stray command, which made the
+ * reconciler propose deleting its own installation record. (XSPEC-343 R2)
+ */
+const INSTALLER_BOOKKEEPING_FILES = new Set(['.manifest.json']);
 
 /**
  * Scan the actual state of UDS artifacts on disk.
@@ -241,6 +250,57 @@ function scanIntegrations(state, projectPath) {
   }
 }
 
+/**
+ * Read a directory, tolerating the read itself failing (race, permissions).
+ *
+ * Deliberately narrow: only `readdirSync` is wrapped. The scan loops used to sit
+ * inside the same `catch {}`, so any programming error in the loop body became
+ * "this agent has no skills/commands" — an empty actual state indistinguishable
+ * from a genuinely empty directory, which downstream reads as "nothing to delete,
+ * install everything".
+ */
+function readDirEntries(dirPath) {
+  try {
+    return readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+let _sourceEntries = null;
+let _shippedCommands = null;
+
+/** Directory names UDS ships under `skills/`, cached per process. */
+function sourceEntryNames() {
+  if (_sourceEntries === null) _sourceEntries = getSkillsSourceEntryNames();
+  return _sourceEntries;
+}
+
+/** Command names UDS ships, cached per process. */
+function shippedCommandNames() {
+  if (_shippedCommands === null) _shippedCommands = new Set(getAvailableCommandNames());
+  return _shippedCommands;
+}
+
+/**
+ * Did UDS put this skill directory here?
+ *
+ * Two positive signals, either is enough:
+ *   1. a directory of the same name exists in UDS's own `skills/` tree — this
+ *      also covers the non-skill siblings (`_shared`, `agents`, …) that an older
+ *      CLI copied in by mistake, so they stay cleanable;
+ *   2. `manifest.skillHashes` records a file under it — authoritative when
+ *      present, though in practice it is sparse (dev-platform: 2 entries for 78
+ *      installed skills), which is exactly why signal 1 has to carry the weight.
+ *
+ * Anything else is the adopter's own, and is warned about rather than deleted.
+ */
+function isUdsProvenance(skillName, manifest, agent, level) {
+  if (sourceEntryNames().has(skillName)) return true;
+  const prefix = `${agent}/${level}/${skillName}/`;
+  return Object.keys(manifest?.skillHashes || {}).some((k) => k.startsWith(prefix));
+}
+
 /**
  * Scan skill installations.
  */
@@ -252,27 +312,32 @@ function scanSkills(state, projectPath, manifest) {
     const skillsDir = getSkillsDirForAgent(agent, level, projectPath);
     if (!skillsDir || !existsSync(skillsDir)) continue;
 
-    try {
-      const entries = readdirSync(skillsDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-        const skillName = entry.name;
-        const key = `skill:${agent}:${level}:${skillName}`;
-        const relPath = level === 'project'
-          ? getRelativePath(projectPath, join(skillsDir, skillName))
-          : join(skillsDir, skillName);
-
-        state.skills.set(key, {
-          relativePath: relPath,
-          hash: null,  // Directory-level hashes tracked in manifest.skillHashes
-          size: null,
-          category: 'skill',
-          sourcePath: null,
-          metadata: { agent, level, skillName, scanned: true }
-        });
-      }
-    } catch {
-      // Ignore read errors
+    for (const entry of readDirEntries(skillsDir)) {
+      if (!entry.isDirectory()) continue;
+      const skillName = entry.name;
+      const key = `skill:${agent}:${level}:${skillName}`;
+      const relPath = level === 'project'
+        ? getRelativePath(projectPath, join(skillsDir, skillName))
+        : join(skillsDir, skillName);
+
+      state.skills.set(key, {
+        relativePath: relPath,
+        hash: null,  // Directory-level hashes tracked in manifest.skillHashes
+        size: null,
+        category: 'skill',
+        sourcePath: null,
+        metadata: {
+          agent,
+          level,
+          skillName,
+          scanned: true,
+          // Whether UDS is the thing that put this directory here. Everything in
+          // 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, manifest, agent, level)
+        }
+      });
     }
   }
 }
@@ -288,27 +353,37 @@ function scanCommands(state, projectPath, manifest) {
     const cmdsDir = getCommandsDirForAgent(agent, level, projectPath);
     if (!cmdsDir || !existsSync(cmdsDir)) continue;
 
-    try {
-      const entries = readdirSync(cmdsDir, { withFileTypes: true });
-      for (const entry of entries) {
-        // Commands can be files (.md) or directories
-        const cmdName = entry.name.replace(/\.md$/, '');
-        const key = `command:${agent}:${level}:${cmdName}`;
-        const relPath = level === 'project'
-          ? getRelativePath(projectPath, join(cmdsDir, entry.name))
-          : join(cmdsDir, entry.name);
-
-        state.commands.set(key, {
-          relativePath: relPath,
-          hash: null,
-          size: null,
-          category: 'command',
-          sourcePath: null,
-          metadata: { agent, level, commandName: cmdName, scanned: true }
-        });
-      }
-    } catch {
-      // Ignore read errors
+    const ext = getCommandFileExtension(agent);
+
+    for (const entry of readDirEntries(cmdsDir)) {
+      if (INSTALLER_BOOKKEEPING_FILES.has(entry.name)) continue;
+
+      // Commands are files named `<name><ext>` (or, for some agents, directories).
+      // Stripping a hard-coded `.md` left every Gemini command as `commit.toml`,
+      // which never matches the desired key `commit`, so all of them were
+      // proposed for deletion.
+      const cmdName = entry.name.endsWith(ext)
+        ? entry.name.slice(0, -ext.length)
+        : entry.name;
+      const key = `command:${agent}:${level}:${cmdName}`;
+      const relPath = level === 'project'
+        ? getRelativePath(projectPath, join(cmdsDir, entry.name))
+        : join(cmdsDir, entry.name);
+
+      state.commands.set(key, {
+        relativePath: relPath,
+        hash: null,
+        size: null,
+        category: 'command',
+        sourcePath: null,
+        metadata: {
+          agent,
+          level,
+          commandName: cmdName,
+          scanned: true,
+          udsManaged: shippedCommandNames().has(cmdName)
+        }
+      });
     }
   }
 }

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

@@ -9,13 +9,24 @@
 
 import { join, basename } from 'path';
 import { getAllStandards, getStandardSource, findOption, getOptionSource } from '../utils/registry.js';
-import { SUPPORTED_AI_TOOLS } from '../core/constants.js';
+import {
+  resolveToolKey,
+  SUPPORTED_AI_TOOLS,
+  MANIFEST_OPTION_BINDINGS,
+  OPTIONS_INSTALL_DIR
+} from '../core/constants.js';
 import { PathResolver } from '../core/paths.js';
 import { computeFileHash } from '../utils/hasher.js';
 import {
   getSkillsDirForAgent,
-  getCommandsDirForAgent
+  getCommandsDirForAgent,
+  getCommandFileExtension
 } from '../config/ai-agent-paths.js';
+import {
+  getAvailableSkillNames,
+  getAvailableCommandNames
+} from '../utils/skills-installer.js';
+import { MARKETPLACE_NAMES_SENTINEL } from '../core/manifest.js';
 
 /**
  * @typedef {Object} FileEntry
@@ -62,6 +73,9 @@ export function calculateDesiredState(projectPath, manifest) {
   // 2. Option files
   calculateOptions(state, manifest);
 
+  // 2b. Extension files (locale/language/framework add-ons)
+  calculateExtensions(state, manifest);
+
   // 3. Integration files (CLAUDE.md, .cursorrules, etc.)
   calculateIntegrations(state, manifest);
 
@@ -137,6 +151,19 @@ function calculateStandards(state, manifest) {
 
 /**
  * Calculate expected option files.
+ *
+ * `manifest.options` is flat — `{ workflow: 'github-flow', test_levels: [...] }` —
+ * and the registry nests options under a standard id and a category key whose
+ * name is not always the same word (`test_levels` vs `test_level`). This function
+ * used to iterate the manifest as if its keys were *standard ids*, look up a
+ * standard named `workflow`, find none, and `continue`. It therefore produced an
+ * **empty** desired option set for every adopter repo, and every installed option
+ * file diffed as "no longer in desired state" — including files the manifest had
+ * explicitly selected. EngramGraph's plan proposed deleting all seven of the
+ * options its own manifest names. (XSPEC-343 R2)
+ *
+ * The desired path is flat too: the installer copies into `.standards/options`,
+ * not into a `<standardId>/<categoryKey>/` tree.
  */
 function calculateOptions(state, manifest) {
   const format = manifest.format || 'ai';
@@ -144,47 +171,89 @@ function calculateOptions(state, manifest) {
 
   if (!manifest.options) return;
 
-  for (const [standardId, optionConfig] of Object.entries(manifest.options)) {
-    if (!optionConfig) continue;
+  for (const binding of MANIFEST_OPTION_BINDINGS) {
+    const key = binding.manifestKeys.find(k => manifest.options[k] != null);
+    if (!key) continue;
 
-    const registryEntry = allStandards.find(s => s.id === standardId);
+    const registryEntry = allStandards.find(s => s.id === binding.standardId);
     if (!registryEntry) continue;
 
-    for (const [categoryKey, selection] of Object.entries(optionConfig)) {
-      const selections = Array.isArray(selection) ? selection : [selection];
-      for (const optionId of selections) {
-        if (typeof optionId !== 'string') continue;
-
-        const option = findOption(registryEntry, categoryKey, optionId);
-        if (!option) continue;
-
-        const source = getOptionSource(option, format);
-        if (!source) continue;
-
-        const fileName = basename(source);
-        const relativePath = `.standards/options/${standardId}/${categoryKey}/${fileName}`;
-        const absSource = PathResolver.getStandardSource(source);
-
-        let hash = null;
-        let size = null;
-        if (absSource) {
-          const hashInfo = computeFileHash(absSource);
-          if (hashInfo) {
-            hash = hashInfo.hash;
-            size = hashInfo.size;
-          }
+    const selection = manifest.options[key];
+    const selections = Array.isArray(selection) ? selection : [selection];
+
+    for (const optionId of selections) {
+      if (typeof optionId !== 'string') continue;
+
+      const option = findOption(registryEntry, binding.categoryKey, optionId);
+      if (!option) continue;
+
+      const source = getOptionSource(option, format);
+      if (!source) continue;
+
+      const relativePath = `${OPTIONS_INSTALL_DIR}/${basename(source)}`;
+      const absSource = PathResolver.getStandardSource(source);
+
+      let hash = null;
+      let size = null;
+      if (absSource) {
+        const hashInfo = computeFileHash(absSource);
+        if (hashInfo) {
+          hash = hashInfo.hash;
+          size = hashInfo.size;
         }
+      }
 
-        state.options.set(relativePath, {
-          relativePath,
-          hash,
-          size,
-          category: 'option',
-          sourcePath: absSource,
-          metadata: { standardId, categoryKey, optionId, format }
-        });
+      state.options.set(relativePath, {
+        relativePath,
+        hash,
+        size,
+        category: 'option',
+        sourcePath: absSource,
+        metadata: { standardId: binding.standardId, categoryKey: binding.categoryKey, optionId, format }
+      });
+    }
+  }
+}
+
+/**
+ * Calculate expected extension files.
+ *
+ * `manifest.extensions` records add-ons installed alongside the standards —
+ * locale packs (`extensions/locales/zh-tw.md`), language style guides, framework
+ * patterns — copied flat into `.standards/` by the installer.
+ *
+ * The calculator had no branch for them at all: the word "extensions" appeared
+ * exactly once in the whole reconciler, in the scanner's empty initialiser. So
+ * every installed extension fell outside the desired state and was proposed for
+ * deletion, while `manifest.extensions` went on listing it. Three repos lost
+ * their 717-line Traditional Chinese locale pack to this before it was noticed —
+ * including one where the removal was applied and committed. (XSPEC-343 R2)
+ */
+function calculateExtensions(state, manifest) {
+  for (const source of (manifest.extensions || [])) {
+    if (typeof source !== 'string' || !source) continue;
+
+    const relativePath = `.standards/${basename(source)}`;
+    const absSource = PathResolver.getStandardSource(source);
+
+    let hash = null;
+    let size = null;
+    if (absSource) {
+      const hashInfo = computeFileHash(absSource);
+      if (hashInfo) {
+        hash = hashInfo.hash;
+        size = hashInfo.size;
       }
     }
+
+    state.standards.set(relativePath, {
+      relativePath,
+      hash,
+      size,
+      category: 'standard',
+      sourcePath: absSource,
+      metadata: { extensionSource: source }
+    });
   }
 }
 
@@ -193,8 +262,19 @@ function calculateOptions(state, manifest) {
  * For integrations we track the UDS marker block, not the entire file.
  */
 function calculateIntegrations(state, manifest) {
-  for (const toolName of (manifest.integrations || [])) {
-    const toolConfig = SUPPORTED_AI_TOOLS[toolName];
+  for (const entry of (manifest.integrations || [])) {
+    // Accept both shapes. `manifest.integrations` is normalised to tool keys by
+    // the v3.5.0 migration, but a repo whose manifest has not been re-read and
+    // rewritten still holds file paths — and treating those as unknown tools
+    // silently produced an EMPTY desired state for integrations, which the
+    // reconciler then read as "delete CLAUDE.md's UDS block". Twenty of
+    // twenty-one adopter repos were in that state on 2026-07-30.
+    //
+    // Tolerating the legacy shape here rather than relying on migration alone
+    // is deliberate: the failure mode is silent and destructive, and the reader
+    // is the last place that can still tell the difference.
+    const toolName = resolveToolKey(entry);
+    const toolConfig = toolName ? SUPPORTED_AI_TOOLS[toolName] : null;
     if (!toolConfig) continue;
 
     const relativePath = toolConfig.file;
@@ -217,13 +297,35 @@ function calculateIntegrations(state, manifest) {
 
 /**
  * Calculate expected skill files.
+ *
+ * The desired set is **what this UDS version ships**, not `manifest.skills.names`.
+ * That field is written once by `init` and by no other code path — across five UDS
+ * upgrades it stayed frozen at its original 32 entries while the shipped set grew
+ * to 55, so every skill installed after init counted as "not desired" and was
+ * proposed for deletion. `uds update` always installs the full set (every call site
+ * passes `skillNames = null`), so the shipped list *is* the desired list.
+ * (XSPEC-343 R1/R2 — 40 of machine-setup's 86 proposed deletions.)
  */
 function calculateSkills(state, projectPath, manifest) {
   const skills = manifest.skills;
   if (!skills || !skills.installed) return;
 
-  const skillNames = skills.names || [];
-  if (skillNames.length === 0) return;
+  // Marketplace installs live inside the plugin, not the project. There is no
+  // project-level desired state to compute, and computing one would mark every
+  // on-disk skill for deletion.
+  if (skills.location === 'marketplace' || (skills.names || []).includes(MARKETPLACE_NAMES_SENTINEL)) return;
+
+  const skillNames = getAvailableSkillNames();
+  if (skillNames.length === 0) {
+    // An empty shipped list means the source tree is unreadable, not that the
+    // project should hold no skills. Returning here would leave `desired` empty
+    // and every installed skill would diff as a deletion — the failure mode this
+    // whole function exists to prevent. Fail loudly instead.
+    throw new Error(
+      'Cannot compute desired skill state: the UDS skills source directory is empty or unreadable. ' +
+      'Refusing to plan (an empty desired state would propose deleting every installed skill).'
+    );
+  }
 
   const installations = skills.installations || [];
 
@@ -254,13 +356,22 @@ function calculateSkills(state, projectPath, manifest) {
 
 /**
  * Calculate expected command files.
+ *
+ * Same reasoning as calculateSkills: derive from what UDS ships, not from the
+ * frozen `manifest.commands.names`. machine-setup's list said 31 while UDS
+ * shipped 51. (XSPEC-343 R1/R2)
  */
 function calculateCommands(state, projectPath, manifest) {
   const commands = manifest.commands;
   if (!commands || !commands.installed) return;
 
-  const commandNames = commands.names || [];
-  if (commandNames.length === 0) return;
+  const commandNames = getAvailableCommandNames();
+  if (commandNames.length === 0) {
+    throw new Error(
+      'Cannot compute desired command state: the UDS commands source directory is empty or unreadable. ' +
+      'Refusing to plan (an empty desired state would propose deleting every installed command).'
+    );
+  }
 
   const installations = commands.installations || [];
 
@@ -269,9 +380,12 @@ function calculateCommands(state, projectPath, manifest) {
     const commandsDir = getCommandsDirForAgent(agent, level, projectPath);
     if (!commandsDir) continue;
 
+    // The installed file carries the agent's extension; the key does not.
+    const ext = getCommandFileExtension(agent);
+
     for (const commandName of commandNames) {
       const relativeBase = level === 'project'
-        ? getRelativePath(projectPath, join(commandsDir, commandName))
+        ? getRelativePath(projectPath, join(commandsDir, `${commandName}${ext}`))
         : null;
 
       if (relativeBase) {

package/src/reconciler/diff-engine.js

@@ -286,8 +286,13 @@ function isUDSManaged(entry) {
   // Files in .standards/ are always UDS-managed
   if (entry.relativePath.startsWith('.standards/')) return true;
 
-  // Scanned skill/command entries are UDS-managed
-  if (entry.category === 'skill' || entry.category === 'command') return true;
+  // Scanned skill/command entries carry a provenance flag from the scanner.
+  // This used to return true unconditionally, which meant every directory in an
+  // adopter's skills folder was ours to delete — including hand-written ones.
+  // (XSPEC-343 R2)
+  if (entry.category === 'skill' || entry.category === 'command') {
+    return entry.metadata?.udsManaged !== false;
+  }
 
   // Integration files with markers
   if (entry.metadata?.hasMarkers) return true;