universal-dev-standards 6.1.1 → 6.2.0

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) {

package/src/utils/integration-generator.js

@@ -3,6 +3,7 @@ import { dirname, join, basename } from 'path';
 import { getLanguageRules } from '../prompts/integrations.js';
 import { computeIntegrationBlockHash } from './hasher.js';
 import { UDS_MARKERS, SUPPORTED_AI_TOOLS, LEGACY_TOOL_MAPPINGS } from '../core/constants.js';
+import { resolveSelectedOptionSources } from './registry.js';
 import { getAgentConfig, getAgentTier } from '../config/ai-agent-paths.js';
 
 /**
@@ -107,24 +108,13 @@ const STANDARD_TASK_MAPPING = {
 /**
  * Standard descriptions for index generation
  */
-const STANDARD_DESCRIPTIONS = {
-  'anti-hallucination.md': 'AI 協作防幻覺規範',
-  'commit-message.ai.yaml': '提交訊息格式',
-  'checkin-standards.md': '程式碼簽入檢查',
-  'logging-standards.md': '日誌記錄標準',
-  'error-code-standards.md': '錯誤碼標準',
-  'testing.ai.yaml': '測試標準',
-  'versioning.md': '語意化版本',
-  'changelog-standards.md': '變更日誌標準',
-  'code-review-checklist.md': '程式碼審查清單',
-  'spec-driven-development.md': '規格驅動開發',
-  'test-completeness-dimensions.md': '測試完整性維度',
-  'git-workflow.ai.yaml': 'Git 工作流程',
-  'developer-memory.ai.yaml': '開發者持久記憶',
-  'project-context-memory.ai.yaml': '專案情境記憶',
-  'zh-tw.md': '繁體中文本地化',
-  'workflow-enforcement.ai.yaml': '工作流程強制執行'
-};
+// STANDARD_DESCRIPTIONS 已移除（XSPEC-358 R1 裁決為方案 A：索引區塊不再列名稱清單）。
+// 移除前的實況值得記錄，因為它是一個**綠燈測試釘住生產環境不成立假設**的實例：
+//   該表有 16 筆真實中文描述，鍵**帶副檔名**（'anti-hallucination.md'）。
+//   init 路徑傳入 copyStandard 的 sourcePath → basename **含副檔名** → 查表命中。
+//   update 路徑傳入 manifest.standards → **不含副檔名**（71/78 筆）→ 查表全 miss。
+//   於是同一個區塊在 `uds init` 後有描述、在 `uds update` 後全是 `名稱 - 名稱`。
+//   單元測試餵的是完整檔名，所以它一直是綠的；dev-platform 實測 78/78 皆 fallback。
 
 /**
  * Commit type templates for different output_language options
@@ -2908,6 +2898,11 @@ export function generateComplianceInstructions(installedStandards, mode, format,
   const sections = [];
 
   if (format === 'markdown') {
+    // 三個清單全空時不得留下一個空標題（XSPEC-358 §1）——
+    // 一個沒有內容的章節，讀起來像「這裡本來該有東西而它不見了」。
+    if (mustFollow.length === 0 && shouldFollow.length === 0) {
+      return '';
+    }
     sections.push('## Standards Compliance Instructions');
     sections.push('');
 
@@ -2936,6 +2931,9 @@ export function generateComplianceInstructions(installedStandards, mode, format,
     }
   } else {
     // Plaintext format
+    if (mustFollow.length === 0 && shouldFollow.length === 0) {
+      return '';
+    }
     sections.push('## Standards Compliance Instructions');
     sections.push('');
 
@@ -2975,71 +2973,108 @@ export function generateStandardsIndex(installedStandards, format, language = 'z
     return '';
   }
 
-  const coreStandards = [];
-  const optionStandards = [];
-
-  // Separate core standards from options
-  for (const standardPath of installedStandards) {
-    const filename = basename(standardPath);
-    const isOption = standardPath.includes('/options/') || standardPath.includes('\\options\\');
-    const description = STANDARD_DESCRIPTIONS[filename] || filename;
-
-    if (isOption) {
-      optionStandards.push({ filename, description, path: standardPath });
-    } else {
-      coreStandards.push({ filename, description, path: standardPath });
-    }
-  }
-
-  const sections = [];
+  const total = installedStandards.length;
+  const optionCount = installedStandards.filter(
+    (p) => p.includes('/options/') || p.includes('\\options\\')
+  ).length;
+  const coreCount = total - optionCount;
+
+  const heading = '## Installed Standards Index';
+  const md = format === 'markdown';
+  const body = language === 'en'
+    ? [
+      `This project has adopted **${total}** UDS standards (${coreCount} core, ${optionCount} options), installed in \`.standards/\`.`,
+      '',
+      'The authoritative list is the `standards` field of `.standards/manifest.json`. Read a standard\'s own file to see what it requires — and check its first line, which is where a deprecated standard says so.'
+    ]
+    : [
+      `本專案採用 UDS 標準共 **${total}** 條（core ${coreCount}、options ${optionCount}），安裝於 \`.standards/\`。`,
+      '',
+      '權威清單為 `.standards/manifest.json` 的 `standards` 欄位。要知道某標準要求什麼，讀它自己的檔案——並看第一行，已棄用的標準會在那裡寫明。'
+    ];
 
-  if (format === 'markdown') {
-    sections.push('## Installed Standards Index');
-    sections.push('');
-    sections.push(language === 'en'
-      ? 'This project has adopted UDS standards. All standards are in `.standards/`:'
-      : '本專案採用 UDS 標準。所有規範位於 `.standards/`：');
-    sections.push('');
+  const plainBody = body.map((l) => l.replace(/`/g, ''));
+  return [heading, '', ...(md ? body : plainBody), ''].join('\n');
+}
 
-    if (coreStandards.length > 0) {
-      sections.push(`### Core (${coreStandards.length} standards)`);
-      for (const std of coreStandards) {
-        sections.push(`- \`${std.filename}\` - ${std.description}`);
-      }
-      sections.push('');
-    }
+/**
+ * Build the generation config for one AI tool from the manifest.
+ *
+ * Both the normal `uds update` path and the reconciler regenerate integration
+ * blocks, and they used to derive this config independently. The reconciler's
+ * copy omitted `categories` entirely, defaulted `outputLanguage` to English, and
+ * looked up `manifest.integrationConfigs` by **tool key** while the manifest
+ * stores it by **file name** — so the lookup always missed. The result was a
+ * strictly poorer block: reconciling machine-setup silently dropped its
+ * "提交訊息語言" and "Standards Compliance Instructions" sections, which the
+ * normal update path had always written. Two generators, one contract, one of
+ * them quietly lossy. (XSPEC-343 R2)
+ *
+ * `integrationConfigs` is deliberately NOT merged in: its `installedStandards`
+ * is a snapshot frozen at install time, and honouring it would reintroduce
+ * exactly the staleness this whole XSPEC is about.
+ *
+ * @param {Object} manifest - Project manifest
+ * @param {string} tool - Tool key (e.g. 'claude-code')
+ * @returns {Object} Config for generateIntegrationContent / writeIntegrationFile
+ */
+function withSelectedOptions(manifest) {
+  const standards = manifest.standards || [];
+  const seen = new Set(standards.map((p) => basename(p)));
+  const extra = resolveSelectedOptionSources(manifest.options, manifest.format || 'ai')
+    .filter((p) => !seen.has(basename(p)));
+  return [...standards, ...extra];
+}
 
-    if (optionStandards.length > 0) {
-      sections.push('### Options');
-      for (const std of optionStandards) {
-        sections.push(`- \`options/${std.filename}\` - ${std.description}`);
-      }
-      sections.push('');
-    }
-  } else {
-    // Plaintext format
-    sections.push('## Installed Standards Index');
-    sections.push('');
-    sections.push(language === 'en'
-      ? 'UDS standards installed in .standards/:'
-      : 'UDS 標準已安裝於 .standards/：');
-    sections.push('');
+export function buildToolIntegrationConfig(manifest, tool) {
+  const selected = manifest.options?.output_language || manifest.options?.commit_language || 'english';
+  const language = selected === 'bilingual'
+    ? 'bilingual'
+    : selected === 'traditional-chinese' ? 'zh-tw' : 'en';
+  const resolved = resolveContentModeForTool(tool, manifest.contentMode || 'auto');
 
-    for (const std of coreStandards) {
-      sections.push(`- ${std.filename} - ${std.description}`);
-    }
+  return {
+    tool,
+    categories: ['anti-hallucination', 'commit-standards', 'code-review'],
+    language,
+    // Pass manifest entries UNCHANGED. Every consumer here documents this
+    // parameter as "standard file paths" and basenames it for display, while
+    // classifying options by `path.includes('/options/')`. Reducing to basenames
+    // first destroys that signal: options silently count as core, so the index
+    // block reported "(70 core, 0 options)" and the minimal block listed option
+    // files under the wrong heading with a path that does not exist on disk.
+    installedStandards: withSelectedOptions(manifest),
+    contentMode: resolved.contentMode,
+    level: resolved.level,
+    outputLanguage: selected,
+    methodology: manifest.methodology
+  };
+}
 
-    if (optionStandards.length > 0) {
-      sections.push('');
-      sections.push('Options:');
-      for (const std of optionStandards) {
-        sections.push(`- options/${std.filename} - ${std.description}`);
-      }
-    }
-    sections.push('');
-  }
+/**
+ * Heading of the index-mode standards block. Not localised — both the English and
+ * the Chinese body sit under this exact string, so it is a stable marker.
+ */
+export const STANDARDS_INDEX_HEADING = '## Installed Standards Index';
 
-  return sections.join('\n');
+/**
+ * Read the standards count declared by an index-mode block.
+ *
+ * XSPEC-358 R1 replaced the enumerated list with a count plus a pointer to the
+ * manifest. Two checks in `uds check` still asserted the old contract by grepping
+ * the integration file for every standard name, so after the change they reported
+ * `5/70` and `0/7` and told the user to run `uds update` — which regenerates the
+ * same non-enumerating block. An unsatisfiable loop. Checks must assert what the
+ * block claims now, not what it used to list. (XSPEC-343 R2 / XSPEC-358 R1)
+ *
+ * @param {string} content - Full integration file content
+ * @returns {number|null} Declared count, or null if this is not an index block
+ */
+export function parseStandardsIndexCount(content) {
+  const at = content.indexOf(STANDARDS_INDEX_HEADING);
+  if (at === -1) return null;
+  const match = content.slice(at).match(/\*\*(\d+)\*\*/);
+  return match ? Number(match[1]) : null;
 }
 
 /**
@@ -3053,7 +3088,15 @@ export function wrapWithMarkers(content, format) {
   const warning = format === 'plaintext'
     ? '# WARNING: This block is managed by UDS (universal-dev-standards). DO NOT manually edit. Use \'npx uds install\' or \'npx uds update\' to modify.'
     : '<!-- WARNING: This block is managed by UDS (universal-dev-standards). DO NOT manually edit. Use \'npx uds install\' or \'npx uds update\' to modify. -->';
-  return `${markers.start}\n${warning}\n${content}\n${markers.end}`;
+  // 冪等：warning 位於 markers **內部**，而 extractMarkedContent 取出的內容也含它，
+  // 於是重新包裝會疊出第二份（dev-platform CLAUDE.md 實測 178/179 兩行完全相同）。
+  // 這裡先剝掉內容開頭既有的 warning，不論上游哪條路徑造成都能修掉。
+  // ⚠️ 未隔離出上游那條路徑——這是防禦性修法，如實記錄其範圍。
+  const stripped = content.replace(
+    /^(?:<!--\s*WARNING: This block is managed by UDS[\s\S]*?-->|#\s*WARNING: This block is managed by UDS[^\n]*)\n?/,
+    ''
+  );
+  return `${markers.start}\n${warning}\n${stripped}\n${markers.end}`;
 }
 
 /**

package/src/utils/registry.js

@@ -1,6 +1,7 @@
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import { MANIFEST_OPTION_BINDINGS } from '../core/constants.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -205,3 +206,41 @@ export function isMultiSelectOption(standard, categoryKey) {
   }
   return standard.options[categoryKey].multiSelect === true;
 }
+
+/**
+ * Resolve the option source paths a manifest's `options` selection installs.
+ *
+ * `manifest.options` is the authoritative record of what the project chose;
+ * `manifest.standards` records option files inconsistently — most repos list
+ * them, machine-setup lists none — so anything counting options from
+ * `manifest.standards` alone reported "0 options" for a project that has seven
+ * of them on disk. (XSPEC-343 R2)
+ *
+ * @param {Object} manifestOptions - `manifest.options`
+ * @param {string} [format='ai'] - Source format
+ * @returns {string[]} Registry-relative source paths, e.g. ai/options/testing/unit-testing.ai.yaml
+ */
+export function resolveSelectedOptionSources(manifestOptions, format = 'ai') {
+  if (!manifestOptions) return [];
+  const all = getAllStandards();
+  const paths = [];
+
+  for (const binding of MANIFEST_OPTION_BINDINGS) {
+    const key = binding.manifestKeys.find((k) => manifestOptions[k] != null);
+    if (!key) continue;
+
+    const standard = all.find((s) => s.id === binding.standardId);
+    if (!standard) continue;
+
+    const selection = manifestOptions[key];
+    for (const optionId of Array.isArray(selection) ? selection : [selection]) {
+      if (typeof optionId !== 'string') continue;
+      const option = findOption(standard, binding.categoryKey, optionId);
+      if (!option) continue;
+      const source = getOptionSource(option, format);
+      if (source) paths.push(source);
+    }
+  }
+
+  return paths;
+}

package/src/utils/skills-installer.js

@@ -15,10 +15,12 @@ import {
   getSkillsDirForAgent,
   getCommandsDirForAgent,
   getSkillsSupportedAgents,
-  getCommandsSupportedAgents
+  getCommandsSupportedAgents,
+  getCommandFileExtension
 } from '../config/ai-agent-paths.js';
 import { computeDirectoryHashes, computeFileHash } from './hasher.js';
 import { isLocalizedLocale } from './locale.js';
+import { getSkillsSourceDir } from './skills-source.js';
 
 // Get the CLI package root directory
 const __filename = fileURLToPath(import.meta.url);
@@ -26,19 +28,8 @@ const __dirname = dirname(__filename);
 const CLI_ROOT = join(__dirname, '..', '..');
 const BUNDLED_DIR = join(CLI_ROOT, 'bundled');
 
-/**
- * Get the Skills source directory.
- * Prioritizes bundled directory (npm install), falls back to development path.
- * @returns {string} Path to skills source directory
- */
-function getSkillsSourceDir() {
-  const bundledPath = join(BUNDLED_DIR, 'skills');
-  if (existsSync(bundledPath)) {
-    return bundledPath;
-  }
-  // Development environment fallback
-  return join(CLI_ROOT, '..', 'skills');
-}
+// getSkillsSourceDir now lives in skills-source.js so github.js resolves the same path.
+// Its previous private copy here was the half that worked; the copy in github.js was not.
 
 /**
  * Get the localized Skills source directory for a given locale.
@@ -108,23 +99,56 @@ export function getAvailableSkillNames() {
     return [];
   }
 
-  const NON_SKILL_ITEMS = [
-    'README.md', 'CONTRIBUTING.template.md',
-    'commands', '.manifest.json', '.DS_Store'
-  ];
-
   try {
     return readdirSync(SKILLS_LOCAL_DIR)
       .filter(item => {
-        if (NON_SKILL_ITEMS.includes(item)) return false;
         const itemPath = join(SKILLS_LOCAL_DIR, item);
-        return statSync(itemPath).isDirectory();
+        if (!statSync(itemPath).isDirectory()) return false;
+        // A skill is a directory containing SKILL.md. Defining it positively rather than
+        // by a deny-list matters: `skills/` also holds agents/, workflows/, ai/, tools/
+        // and _shared/, which belong to other installers. The old deny-list named only
+        // some of them, so the rest were treated as skills whose SKILL.md "failed to
+        // install" — 5 phantom failures that failed the whole install transaction.
+        // A new sibling directory now costs nothing; under a deny-list it would break
+        // installation until someone remembered to add it.
+        return existsSync(join(itemPath, 'SKILL.md'));
       });
   } catch {
     return [];
   }
 }
 
+/**
+ * Every directory name in the skills source tree, including the ones that are not
+ * skills (`_shared`, `agents`, `ai`, `commands`, `tools`, `workflows`).
+ *
+ * Used as a provenance test: if a directory in an adopter's skills folder has a
+ * counterpart here, UDS put it there. If it does not, UDS did not — it is either
+ * an adopter's own skill or an artefact of a UDS version too old to reason about,
+ * and deleting it is not this tool's call to make.
+ *
+ * The distinction matters because an older CLI copied the non-skill siblings in
+ * by mistake, so a strict "is it a skill we ship" test would leave those behind
+ * while a naive "is it in the skills folder" test deletes hand-written skills.
+ * dev-platform has fourteen of those. (XSPEC-343 R2)
+ *
+ * @returns {Set<string>} Directory names present in the skills source tree
+ */
+export function getSkillsSourceEntryNames() {
+  if (!existsSync(SKILLS_LOCAL_DIR)) {
+    return new Set();
+  }
+  try {
+    return new Set(
+      readdirSync(SKILLS_LOCAL_DIR, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+    );
+  } catch {
+    return new Set();
+  }
+}
+
 /**
  * Get list of available command names from local directory
  * @returns {string[]} Array of command names (without .md extension)
@@ -550,19 +574,10 @@ export async function installCommandsForAgent(agent, level = 'project', commandN
   return results;
 }
 
-/**
- * Get the appropriate file extension for commands based on agent
- * @param {string} agent - Agent identifier
- * @returns {string} File extension (including the dot)
- */
-function getCommandFileExtension(agent) {
-  // Gemini CLI uses TOML format
-  if (agent === 'gemini-cli') {
-    return '.toml';
-  }
-  // Most agents use markdown
-  return '.md';
-}
+// getCommandFileExtension moved to config/ai-agent-paths.js — the reconciler's
+// scanner needs the same mapping, and a second private copy is how the writer
+// and the reader drift apart. It now reads `commandFormat` from the agent config
+// instead of hard-coding one agent id. (XSPEC-343 R2)
 
 /**
  * Install a single command to target directory