universal-dev-standards 5.7.1 → 5.7.2

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

@@ -1,7 +1,7 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 5.7.1
-translation_version: 5.7.1
+source_version: 5.7.2
+translation_version: 5.7.2
 last_synced: 2026-05-08
 status: current
 ---

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

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

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

@@ -1,7 +1,7 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 5.7.1
-translation_version: 5.7.1
+source_version: 5.7.2
+translation_version: 5.7.2
 last_synced: 2026-05-08
 status: current
 ---

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

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

package/package.json

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

package/src/commands/check.js

@@ -36,7 +36,7 @@ import { checkForUpdates } from '../utils/npm-registry.js';
 import { writeUpdateCache } from '../utils/update-checker.js';
 import { StandardValidator } from '../utils/standard-validator.js';
 import { WorkflowGate } from '../utils/workflow-gate.js';
-import { t, getLanguage, setLanguage, isLanguageExplicitlySet } from '../i18n/messages.js';
+import { t, setLanguage, isLanguageExplicitlySet } from '../i18n/messages.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
 
 /**
@@ -112,13 +112,42 @@ function performFileIntegrityCheck(projectPath, manifest, msg) {
     console.log(chalk.gray(`    ${msg.checkingExistence}`));
     console.log();
 
-    // Check standards
+    // Check standards — support both legacy path format and current ID format
+    const allStdsLegacy = getAllStandards();
+    const legacyFormat = manifest.format || 'ai';
     for (const std of manifest.standards) {
-      const filePath = join(projectPath, '.standards', std.split('/').pop());
+      // Option file paths (ai/options/...) use a subdirectory; handle separately
+      if (std.includes('/options/') || std.startsWith('options/')) {
+        const fileName = std.split('/').pop();
+        const filePath = join(projectPath, '.standards', 'options', fileName);
+        if (existsSync(filePath)) {
+          fileStatus.noHash.push(`.standards/options/${fileName}`);
+        } else {
+          fileStatus.missing.push(`.standards/options/${fileName}`);
+        }
+        continue;
+      }
+      // ID format (no '/' or '.'): resolve via registry to get actual filename
+      let fileName;
+      if (!std.includes('/') && !std.includes('.')) {
+        const entry = allStdsLegacy.find(s => s.id === std);
+        if (entry) {
+          const src = entry.source;
+          const sourcePath = typeof src === 'string'
+            ? src
+            : (src?.[legacyFormat] || src?.ai || src?.human || std);
+          fileName = basename(sourcePath);
+        } else {
+          fileName = std;
+        }
+      } else {
+        fileName = std.split('/').pop();
+      }
+      const filePath = join(projectPath, '.standards', fileName);
       if (existsSync(filePath)) {
-        fileStatus.noHash.push(`.standards/${std.split('/').pop()}`);
+        fileStatus.noHash.push(`.standards/${fileName}`);
       } else {
-        fileStatus.missing.push(`.standards/${std.split('/').pop()}`);
+        fileStatus.missing.push(`.standards/${fileName}`);
       }
     }
 
@@ -496,7 +525,7 @@ async function showSingleFileDiff(projectPath, manifest, relativePath, msg) {
   const fullPath = join(projectPath, relativePath);
 
   // Get current content
-  let currentContent = '';
+  let currentContent;
   try {
     currentContent = readFileSync(fullPath, 'utf-8');
   } catch {
@@ -739,10 +768,23 @@ async function migrateToHashBasedTracking(projectPath, manifest) {
   const now = new Date().toISOString();
   let count = 0;
 
-  // Process standards
+  // Process standards — support both legacy path format and current ID format
+  const format = manifest.format || 'ai';
+  const allStds = getAllStandards();
   for (const std of manifest.standards) {
-    const fileName = basename(std);
-    const relativePath = (std.includes('options/')
+    // Resolve path: ID format → look up source path from registry
+    let resolvedPath = std;
+    if (!std.includes('/') && !std.includes('.')) {
+      const entry = allStds.find(s => s.id === std);
+      if (entry) {
+        const src = entry.source;
+        resolvedPath = typeof src === 'string'
+          ? src
+          : (src?.[format] || src?.ai || src?.human || std);
+      }
+    }
+    const fileName = basename(resolvedPath);
+    const relativePath = (resolvedPath.includes('options/')
       ? join('.standards', 'options', fileName)
       : join('.standards', fileName)).replace(/\\/g, '/');
     const fullPath = join(projectPath, relativePath);

package/src/commands/config.js

@@ -8,8 +8,7 @@ import { msg, t as getMessages, setLanguage, isLanguageExplicitlySet } from '../
 import {
   getOptionSource,
   findOption,
-  getAllStandards,
-  getStandardSource
+  getAllStandards
 } from '../utils/registry.js';
 import {
   copyStandard,
@@ -641,7 +640,7 @@ export async function runProjectConfiguration(options) {
           try {
             unlinkSync(filePath);
             console.log(chalk.gray(`  ${msgObj.removed}: ${getToolFilePath(tool)}`));
-          } catch (err) {
+          } catch {
             console.log(chalk.yellow(`  ${msgObj.couldNotRemove}: ${getToolFilePath(tool)}`));
           }
         }

package/src/commands/flow.js

@@ -15,11 +15,11 @@
  */
 
 import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { join, basename } from 'path';
+import { join } from 'path';
 import yaml from 'js-yaml';
 import { parseFlow } from '../flow/flow-parser.js';
 import { listFlows, validateFlowById, diffFlows } from '../flow/flow-commands.js';
-import { exportBundle, importBundle, validateBundle } from '../flow/flow-bundler.js';
+import { exportBundle, importBundle } from '../flow/flow-bundler.js';
 
 /**
  * 從互動式回答建立 Flow 物件。
@@ -105,7 +105,7 @@ export function loadAllFlows(projectPath) {
 /**
  * CLI action: uds flow create
  */
-export async function flowCreateCommand(options) {
+export async function flowCreateCommand(_options) {
   const inquirer = await import('inquirer');
   const projectPath = process.cwd();
 

package/src/commands/init.js

@@ -65,7 +65,7 @@ export async function initCommand(options) {
   console.log();
 
   // Configuration object
-  let config = {};
+  let config;
 
   if (!options.yes) {
     // Interactive Mode
@@ -218,7 +218,7 @@ async function setupHuskyHook(projectPath) {
         console.log(chalk.gray('  Initializing husky...'));
         execSync('npx husky init', { stdio: 'ignore', cwd: projectPath });
       }
-    } catch (e) {
+    } catch {
       // Ignore, might already be init
     }
 
@@ -249,7 +249,7 @@ async function setupHuskyHook(projectPath) {
         writeFileSync(preCommitPath, content + `\n# UDS Standard Check\n${udsCmd}\n`, 'utf-8');
         try {
           execSync(`chmod +x ${preCommitPath}`);
-        } catch (e) {
+        } catch {
           // Ignore chmod failures on systems that don't support it
         }
         console.log(chalk.green('  ✓ Adding uds check to pre-commit hook'));

package/src/commands/update.js

@@ -204,10 +204,23 @@ function checkNewStandards(manifest) {
   // Include all reference and skill standards
   const eligibleStandards = registryStandards.filter(s => s.category === 'reference' || s.category === 'skill');
 
-  // Get installed standard basenames for comparison
-  const installedBasenames = new Set(
-    (manifest.standards || []).map(s => basename(s))
-  );
+  // Get installed standard basenames for comparison.
+  // Handles both legacy path format ("ai/standards/foo.ai.yaml" → basename "foo.ai.yaml")
+  // and v3.4.0 ID format ("foo" → resolve to source path, then get basename).
+  const installedBasenames = new Set();
+  for (const s of (manifest.standards || [])) {
+    if (s.includes('/options/') || s.startsWith('options/')) continue; // Skip option paths
+    if (!s.includes('/') && !s.includes('.')) {
+      // ID format: resolve to actual source filename via registry
+      const entry = registryStandards.find(r => r.id === s);
+      if (entry) {
+        const sourcePath = getStandardSource(entry, format);
+        if (sourcePath) installedBasenames.add(basename(sourcePath));
+      }
+    } else {
+      installedBasenames.add(basename(s));
+    }
+  }
 
   // Find standards in registry that are not yet installed
   const newStandards = [];
@@ -394,9 +407,20 @@ export async function updateCommand(options) {
 
   // List files to update
   console.log(chalk.gray(msg.filesToUpdate));
+  const displayFormat = manifest.format || 'ai';
+  const allStdsDisplay = getAllStandards();
   for (const std of manifest.standards) {
-    const fileName = std.split('/').pop();
-    const displayPath = getStandardTargetDir(std) + '/' + fileName;
+    // ID format: resolve to source path for display
+    let resolvedStd = std;
+    if (!std.includes('/') && !std.includes('.')) {
+      const entry = allStdsDisplay.find(r => r.id === std);
+      if (entry) {
+        const src = getStandardSource(entry, displayFormat);
+        if (src) resolvedStd = src;
+      }
+    }
+    const fileName = resolvedStd.split('/').pop();
+    const displayPath = getStandardTargetDir(resolvedStd) + '/' + fileName;
     console.log(chalk.gray(`  ${displayPath}`));
   }
   for (const ext of manifest.extensions) {
@@ -445,8 +469,19 @@ export async function updateCommand(options) {
   };
 
   // Update standards
+  const updateFormat = manifest.format || 'ai';
+  const allStdsUpdate = getAllStandards();
   for (const std of manifest.standards) {
-    const result = await copyStandard(std, getStandardTargetDir(std), projectPath);
+    // ID format: resolve to source path for copying
+    let sourcePath = std;
+    if (!std.includes('/') && !std.includes('.')) {
+      const entry = allStdsUpdate.find(r => r.id === std);
+      if (entry) {
+        const src = getStandardSource(entry, updateFormat);
+        if (src) sourcePath = src;
+      }
+    }
+    const result = await copyStandard(sourcePath, getStandardTargetDir(sourcePath), projectPath);
     if (result.success) {
       results.updated.push(std);
     } else {
@@ -602,10 +637,21 @@ export async function updateCommand(options) {
     manifest.fileHashes = {};
   }
 
-  // Update hashes for standards
+  // Update hashes for standards (handles both ID format and legacy path format)
+  const hashFormat = manifest.format || 'ai';
+  const allStdsHash = getAllStandards();
   for (const std of manifest.standards) {
-    const fileName = basename(std);
-    const relativePath = (std.includes('options/')
+    // Resolve ID-format to source path
+    let resolvedPath = std;
+    if (!std.includes('/') && !std.includes('.')) {
+      const entry = allStdsHash.find(r => r.id === std);
+      if (entry) {
+        const src = getStandardSource(entry, hashFormat);
+        if (src) resolvedPath = src;
+      }
+    }
+    const fileName = basename(resolvedPath);
+    const relativePath = (resolvedPath.includes('options/')
       ? join('.standards', 'options', fileName)
       : join('.standards', fileName)).replace(/\\/g, '/');
     const fullPath = join(projectPath, relativePath);
@@ -705,9 +751,20 @@ export async function updateCommand(options) {
 
   // Post-update integrity check: detect and restore missing files
   const allTrackedFiles = [];
+  const trackFormat = manifest.format || 'ai';
+  const allStdsTrack = getAllStandards();
   for (const std of manifest.standards) {
-    const fileName = basename(std);
-    const relativePath = std.includes('options/')
+    // Resolve ID-format to source path for computing relativePath
+    let resolvedStd = std;
+    if (!std.includes('/') && !std.includes('.')) {
+      const entry = allStdsTrack.find(r => r.id === std);
+      if (entry) {
+        const src = getStandardSource(entry, trackFormat);
+        if (src) resolvedStd = src;
+      }
+    }
+    const fileName = basename(resolvedStd);
+    const relativePath = resolvedStd.includes('options/')
       ? join('.standards', 'options', fileName)
       : join('.standards', fileName);
     allTrackedFiles.push(relativePath);

package/src/core/manifest.js

@@ -1,20 +1,21 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { join, dirname } from 'path';
+import { join, dirname, basename } from 'path';
+import { getAllStandards } from '../utils/registry.js';
 
 /**
- * UDS Manifest Schema v3.3.0
+ * UDS Manifest Schema v3.4.0
  * Central configuration and state tracking for UDS installations
  */
 
 /**
  * Supported manifest schema versions
  */
-export const SUPPORTED_SCHEMA_VERSIONS = ['3.0.0', '3.1.0', '3.2.0', '3.3.0'];
+export const SUPPORTED_SCHEMA_VERSIONS = ['3.0.0', '3.1.0', '3.2.0', '3.3.0', '3.4.0'];
 
 /**
  * Current manifest schema version
  */
-export const CURRENT_SCHEMA_VERSION = '3.3.0';
+export const CURRENT_SCHEMA_VERSION = '3.4.0';
 
 /**
  * Default manifest values
@@ -294,6 +295,11 @@ export function migrateManifest(manifest) {
     migrated = migrateToV330(migrated);
   }
 
+  if (currentVersion < '3.4.0') {
+    // Migrate to 3.4.0 - convert standards array from path format to ID format
+    migrated = migrateToV340(migrated);
+  }
+
   // Update schema version
   migrated.version = CURRENT_SCHEMA_VERSION;
 
@@ -367,6 +373,83 @@ function migrateToV330(manifest) {
   };
 }
 
+/**
+ * Migration to version 3.4.0
+ * Converts standards array from legacy path format ("ai/standards/foo.ai.yaml",
+ * "core/foo.md") to registry ID format ("foo"). Deduplicates entries that
+ * refer to the same standard via different format paths (ai vs human).
+ * @param {Object} manifest - V3.3.x manifest
+ * @returns {Object} V3.4.0 compatible manifest
+ */
+function migrateToV340(manifest) {
+  return {
+    ...manifest,
+    version: '3.4.0',
+    standards: migrateStandardsPathsToIds(manifest.standards || [])
+  };
+}
+
+/**
+ * Convert a standards array from legacy path format to registry ID format.
+ * Entries that already look like IDs (no "/" or ".") are kept as-is.
+ * Path entries are matched against the registry's source.ai / source.human
+ * fields (exact path match or basename match), then replaced with the
+ * registry ID. Entries that match no registry standard are dropped.
+ *
+ * @param {string[]} standards - Standards array (may be IDs or legacy paths)
+ * @returns {string[]} Sorted, deduplicated array of registry IDs
+ */
+export function migrateStandardsPathsToIds(standards) {
+  if (!standards || standards.length === 0) return [];
+
+  const hasPathFormat = standards.some(
+    s => typeof s === 'string' && (s.includes('/') || s.includes('.'))
+  );
+  if (!hasPathFormat) return standards;
+
+  const allStandards = getAllStandards();
+  const ids = new Set();
+  // Option file paths (ai/options/...) have no short-ID equivalent; collect separately
+  const optionPaths = [];
+
+  for (const entry of standards) {
+    if (typeof entry !== 'string') continue;
+
+    // Already an ID (no path separators or extensions)
+    if (!entry.includes('/') && !entry.includes('.')) {
+      ids.add(entry);
+      continue;
+    }
+
+    // Option file paths (e.g. ai/options/commit-message/english.ai.yaml):
+    // no registry ID equivalent — preserve as-is so update/check can manage them
+    if (entry.includes('/options/') || entry.includes('options/')) {
+      optionPaths.push(entry);
+      continue;
+    }
+
+    // Base-standard path format — find matching registry entry
+    let matched = false;
+    for (const s of allStandards) {
+      const src = s.source;
+      const paths = typeof src === 'string'
+        ? [src]
+        : Object.values(src || {}).filter(p => typeof p === 'string');
+
+      if (paths.some(p => p === entry || basename(p) === basename(entry))) {
+        ids.add(s.id);
+        matched = true;
+        break;
+      }
+    }
+    // Unmatched non-option paths are silently dropped (standard removed from registry)
+    void matched;
+  }
+
+  // Return: sorted IDs first, then option paths (preserving order)
+  return [...ids].sort().concat(optionPaths);
+}
+
 /**
  * Ensure all required fields exist on a manifest that already has the current
  * schema version. Older CLIs may have stamped the version number without
@@ -398,9 +481,15 @@ function ensureRequiredFields(manifest) {
     }
   }
 
+  // Safety net: convert any remaining path-format standards to IDs.
+  // Runs even at current schema version in case a manifest was written with
+  // the wrong format by an older CLI or a partial migration.
+  const standards = migrateStandardsPathsToIds(manifest.standards || []);
+
   return {
     ...manifest,
     options,
+    standards,
     contentMode: manifest.contentMode || 'index',
     fileHashes: normalizedHashes,
     skillHashes: manifest.skillHashes || {},

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

@@ -82,8 +82,25 @@ function calculateStandards(state, manifest) {
   const allStandards = getAllStandards();
 
   for (const standardId of (manifest.standards || [])) {
-    // Find registry entry for this standard
-    const registryEntry = allStandards.find(s => s.id === standardId);
+    // Skip option file paths — they are handled by calculateOptions, not this function.
+    // Option paths look like "ai/options/commit-message/english.ai.yaml".
+    if (standardId.includes('/options/') || standardId.startsWith('options/')) continue;
+
+    // Primary lookup: match by registry ID
+    let registryEntry = allStandards.find(s => s.id === standardId);
+
+    // Fallback: legacy path-format manifest entry (e.g. "ai/standards/foo.ai.yaml").
+    // Handles manifests that have not yet been migrated to v3.4.0 ID format.
+    if (!registryEntry && (standardId.includes('/') || standardId.includes('.'))) {
+      registryEntry = allStandards.find(s => {
+        const src = s.source;
+        const paths = typeof src === 'string'
+          ? [src]
+          : Object.values(src || {}).filter(p => typeof p === 'string');
+        return paths.some(p => p === standardId || basename(p) === basename(standardId));
+      });
+    }
+
     if (!registryEntry) continue;
 
     const source = getStandardSource(registryEntry, format);

package/src/utils/friction-detector.js

@@ -14,6 +14,7 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { compareFileHash, hasFileHashes, computeFileHash } from './hasher.js';
 import { SUPPORTED_AI_TOOLS } from '../core/constants.js';
+import { getAllStandards, getStandardSource } from './registry.js';
 
 /**
  * Run friction detection on a UDS installation
@@ -113,9 +114,20 @@ function detectUnusedStandards(projectPath, manifest) {
 
   const allConfigText = configContents.join('\n');
 
-  // Check each standard file
+  // Check each standard file (handles both ID format and legacy path format)
+  const allStdsFriction = getAllStandards();
+  const frictionFormat = manifest.format || 'ai';
   const standardFiles = (manifest.standards || []).map(s => {
-    return s.includes('/') ? s.split('/').pop() : s;
+    if (!s.includes('/') && !s.includes('.')) {
+      // ID format: resolve to actual filename
+      const entry = allStdsFriction.find(r => r.id === s);
+      if (entry) {
+        const src = getStandardSource(entry, frictionFormat);
+        if (src) return src.split('/').pop();
+      }
+      return s;
+    }
+    return s.split('/').pop();
   });
 
   for (const fileName of standardFiles) {

package/src/utils/health-checker.js

@@ -16,6 +16,7 @@ import { join } from 'path';
 import { readManifest } from './copier.js';
 import { compareFileHash, hasFileHashes } from './hasher.js';
 import { SUPPORTED_AI_TOOLS } from '../core/constants.js';
+import { getAllStandards, getStandardSource } from './registry.js';
 
 /**
  * Run Layer 1 health check on a UDS installation
@@ -64,8 +65,22 @@ export function runHealthCheck(projectPath) {
 
   // Check 4: Each standard file in manifest exists
   if (manifest.standards && Array.isArray(manifest.standards)) {
+    const allStds = getAllStandards();
+    const stdFormat = manifest.format || 'ai';
     for (const standardId of manifest.standards) {
-      const fileName = standardId.includes('/') ? standardId.split('/').pop() : standardId;
+      // Resolve ID-format to actual filename via registry
+      let fileName;
+      if (!standardId.includes('/') && !standardId.includes('.')) {
+        const entry = allStds.find(s => s.id === standardId);
+        if (entry) {
+          const src = getStandardSource(entry, stdFormat);
+          fileName = src ? src.split('/').pop() : standardId;
+        } else {
+          fileName = standardId;
+        }
+      } else {
+        fileName = standardId.split('/').pop();
+      }
       const filePath = join(standardsDir, fileName);
       if (!existsSync(filePath)) {
         issues.push({

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "5.7.1",
+  "version": "5.7.2",
   "lastUpdated": "2026-04-16",
   "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": "5.7.1"
+      "version": "5.7.2"
     },
     "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": "5.7.1",
+      "version": "5.7.2",
       "note": "Skills are now included in the main repository under skills/"
     }
   },