universal-dev-standards 6.1.1 → 6.2.1

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;

package/src/reconciler/manifest-migrator.js

@@ -17,6 +17,7 @@ import {
 } from '../core/manifest.js';
 import { computeFileHash, computeIntegrationBlockHash } from '../utils/hasher.js';
 import { SUPPORTED_AI_TOOLS } from '../core/constants.js';
+import { resolveToolKey } from '../core/constants.js';
 
 /**
  * Migrate manifest to latest schema and backfill missing hashes.
@@ -144,8 +145,10 @@ export function backfillFileHashes(projectPath, manifest) {
   }
 
   // Backfill integration block hashes
-  for (const toolName of (updated.integrations || [])) {
-    const toolConfig = SUPPORTED_AI_TOOLS[toolName];
+  for (const entry of (updated.integrations || [])) {
+    // 兩種形狀都要能解出工具（XSPEC-343 R1）
+    const toolName = resolveToolKey(entry);
+    const toolConfig = toolName ? SUPPORTED_AI_TOOLS[toolName] : null;
     if (!toolConfig) continue;
     const filePath = join(projectPath, toolConfig.file);
     if (!updated.integrationBlockHashes[toolConfig.file] && existsSync(filePath)) {

package/src/reconciler/plan-executor.js

@@ -14,12 +14,13 @@
 import { existsSync, unlinkSync, mkdirSync, rmSync, copyFileSync, statSync } from 'fs';
 import { join, dirname } from 'path';
 import { copyStandard } from '../utils/copier.js';
-import { writeIntegrationFile } from '../utils/integration-generator.js';
+import { writeIntegrationFile, buildToolIntegrationConfig } from '../utils/integration-generator.js';
 import {
   installSkillsToMultipleAgents,
   installCommandsToMultipleAgents
 } from '../utils/skills-installer.js';
 import { writeManifest } from '../core/manifest.js';
+import { getRepositoryInfo } from '../utils/registry.js';
 import { displayLanguageToLocale } from '../utils/locale.js';
 import { computeFileHash } from '../utils/hasher.js';
 import { createBackup, cleanupBackups } from './backup-manager.js';
@@ -146,6 +147,24 @@ export async function executePlan(projectPath, plan, manifest, options = {}) {
     }
   }
 
+  // Record the version we just reconciled to — but only on a clean run, mirroring
+  // `uds update`'s rule (a partial failure must stay retryable).
+  //
+  // Without this the reconciler applied everything and advanced nothing: the repo
+  // still recorded 6.1.0, `uds check` still said "behind the latest release", and
+  // the weekly staleness scout — which reads exactly `upstream.version` — kept
+  // reporting the repo as stale after a fully successful reconcile. (XSPEC-343 R2)
+  if (!dryRun && results.every(r => r.success)) {
+    const version = getRepositoryInfo()?.standards?.version;
+    if (version) {
+      updatedManifest.upstream = {
+        ...(updatedManifest.upstream || {}),
+        version,
+        installed: new Date().toISOString().split('T')[0]
+      };
+    }
+  }
+
   // Write updated manifest
   if (!dryRun) {
     try {
@@ -304,6 +323,21 @@ function executeMigrateBlock(projectPath, action, manifest) {
     if (result.blockHashInfo) {
       manifest.integrationBlockHashes[result.path] = result.blockHashInfo;
     }
+    // `init` also records integration files in the whole-file `fileHashes`, which
+    // is what `uds check`'s File Integrity compares. Rewriting the block without
+    // refreshing that entry left the file permanently reported as "modified" —
+    // a successful reconcile that reads, afterwards, as a damaged install.
+    // (XSPEC-343 R2)
+    const tracked = manifest.fileHashes?.[result.path];
+    if (tracked) {
+      const info = computeFileHash(join(projectPath, result.path));
+      if (info) {
+        manifest.fileHashes[result.path] = {
+          ...info,
+          installedAt: tracked.installedAt || new Date().toISOString()
+        };
+      }
+    }
     return { action, success: true };
   }
 
@@ -341,10 +375,19 @@ async function executeSkillBatch(projectPath, skillActions, manifest) {
 
     if (skillNames.length > 0) {
       try {
+        // The locale argument was omitted here while the command path below
+        // passes it, so a reconcile silently reinstalled every skill in English.
+        // telemetry-server lost 59 zh-TW skill files to this before it was caught,
+        // and its manifest went on recording `skills.locale: zh-TW` throughout.
+        // Prefer the recorded skills locale; fall back to the display language,
+        // which is what `uds update` uses. (XSPEC-343 R2)
+        const skillLocale = manifest.skills?.locale
+          || displayLanguageToLocale(manifest?.options?.display_language);
         const installResult = await installSkillsToMultipleAgents(
           manifest.skills.installations,
           skillNames,
-          projectPath
+          projectPath,
+          skillLocale
         );
 
         if (installResult.allFileHashes) {
@@ -434,20 +477,16 @@ async function executeCommandBatch(projectPath, commandActions, manifest) {
 
 /**
  * Build integration generation config from manifest.
+ *
+ * Delegates to the shared builder so the reconciler and `uds update` generate the
+ * same block. The private copy that used to live here omitted `categories`,
+ * defaulted the output language to English, and read `integrationConfigs` by tool
+ * key when the manifest stores it by file name — so reconciling a repo silently
+ * dropped sections the normal update path always wrote. (XSPEC-343 R2)
  */
 function buildIntegrationConfig(manifest, toolName) {
   return {
-    tool: toolName,
-    installedStandards: (manifest.standards || []).map(s =>
-      s.startsWith('.standards/') ? s : `.standards/${s}`
-    ),
-    format: manifest.format || 'ai',
-    contentMode: manifest.contentMode || 'index',
-    language: manifest.integrationConfigs?.[toolName]?.language || 'en',
-    outputLanguage: manifest.integrationConfigs?.[toolName]?.outputLanguage || manifest.integrationConfigs?.[toolName]?.commitLanguage || 'english',
-    installedSkills: manifest.skills?.names || [],
-    installedCommands: manifest.commands?.names || [],
-    methodology: manifest.methodology,
-    ...(manifest.integrationConfigs?.[toolName] || {})
+    ...buildToolIntegrationConfig(manifest, toolName),
+    format: manifest.format || 'ai'
   };
 }

package/src/uninstallers/integration-uninstaller.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { extractMarkedContent } from '../utils/integration-generator.js';
 import { SUPPORTED_AI_TOOLS } from '../core/constants.js';
+import { resolveIntegrationFile } from '../core/constants.js';
 
 /**
  * Get the format for a given integration file name
@@ -36,7 +37,12 @@ export async function uninstallIntegrations(projectPath, manifest, options = {})
     return result;
   }
 
-  for (const fileName of integrations) {
+  for (const entry of integrations) {
+    // Accept both shapes: this uninstaller was written against file names,
+    // while the reconciler reads the same field as tool keys. Normalising the
+    // manifest to one shape fixes one consumer and breaks the other, so both
+    // resolve through the shared helper instead. (XSPEC-343 R1)
+    const fileName = resolveIntegrationFile(entry) || entry;
     const filePath = join(projectPath, fileName);
 
     if (!existsSync(filePath)) {

package/src/utils/config-loader.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 export class ConfigLoader {
   constructor(cwd = process.cwd()) {

package/src/utils/config-manager.js

@@ -2,7 +2,7 @@ import { ConfigLoader } from './config-loader.js';
 import { ConfigMerger } from './config-merger.js';
 import fs from 'fs';
 import path from 'path';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 export class ConfigManager {
   constructor(cwd = process.cwd()) {

package/src/utils/github.js

@@ -4,6 +4,7 @@ import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import https from 'https';
 import { setTimeout as delay } from 'timers/promises';
+import { getSkillsSourceDir } from './skills-source.js';
 
 // Re-export agent-specific functions from ai-agent-paths for unified API
 export {
@@ -26,7 +27,10 @@ const SKILLS_RAW_BASE = 'https://raw.githubusercontent.com/AsiaOstrich/universal
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const CLI_ROOT = join(__dirname, '..', '..');
-const SKILLS_LOCAL_DIR = join(CLI_ROOT, '..', 'skills', 'claude-code');
+
+// Resolved centrally — this file used to hardcode `<CLI_ROOT>/../skills/claude-code`, a
+// layout that no longer exists in either a checkout or an npm install. See skills-source.js.
+const SKILLS_LOCAL_DIR = getSkillsSourceDir();
 
 /**
  * Status codes that are safe to retry (transient errors)

package/src/utils/hasher.js

@@ -2,6 +2,7 @@ import { createHash } from 'crypto';
 import { readFileSync, statSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { UDS_MARKERS } from '../core/constants.js';
+import { resolveIntegrationFile } from '../core/constants.js';
 
 /**
  * Compute SHA-256 hash for a file
@@ -109,10 +110,12 @@ export function getFileStatusSummary(projectPath, manifest) {
         source: e,
         target: join('.standards', e.split('/').pop())
       })),
-      ...manifest.integrations.map(i => ({
-        source: i,
-        target: i
-      }))
+      // `integrations` holds file names in most repos and tool keys in some
+      // (XSPEC-343 R1) — resolve so both shapes yield a real path.
+      ...manifest.integrations.map(i => {
+        const f = resolveIntegrationFile(i) || i;
+        return { source: f, target: f };
+      })
     ];
 
     for (const file of allFiles) {