universal-dev-standards 6.1.1 → 6.2.0

package/src/commands/check.js

@@ -30,7 +30,7 @@ import {
   parseReferences,
   compareStandardsWithReferences
 } from '../utils/reference-sync.js';
-import { extractMarkedContent, getToolFilePath } from '../utils/integration-generator.js';
+import { extractMarkedContent, getToolFilePath, parseStandardsIndexCount } from '../utils/integration-generator.js';
 import { getToolFormat } from '../core/constants.js';
 import { checkForUpdates } from '../utils/npm-registry.js';
 import { writeUpdateCache } from '../utils/update-checker.js';
@@ -39,6 +39,7 @@ import { WorkflowGate } from '../utils/workflow-gate.js';
 import { t, setLanguage, isLanguageExplicitlySet } from '../i18n/messages.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
 import { lintAll as lintI18nAll, partitionFindings as partitionI18nFindings } from '../lint/i18n.js';
+import { resolveIntegrationFile } from '../core/constants.js';
 
 /**
  * Display the summary of file integrity status
@@ -161,7 +162,9 @@ function performFileIntegrityCheck(projectPath, manifest, msg) {
     }
 
     // Check integrations
-    for (const int of manifest.integrations) {
+    for (const intEntry of manifest.integrations) {
+      // 兩種形狀都要能解出路徑（XSPEC-343 R1）
+      const int = resolveIntegrationFile(intEntry) || intEntry;
       const filePath = join(projectPath, int);
       if (existsSync(filePath)) {
         fileStatus.noHash.push(int);
@@ -727,7 +730,9 @@ function removeFromManifest(manifest, relativePath) {
   const fileName = basename(relativePath);
   manifest.standards = manifest.standards.filter(s => !s.endsWith(fileName));
   manifest.extensions = manifest.extensions.filter(e => typeof e !== 'string' || !e.endsWith(fileName));
-  manifest.integrations = manifest.integrations.filter(i => i !== relativePath);
+  manifest.integrations = manifest.integrations.filter(
+    i => (resolveIntegrationFile(i) || i) !== relativePath
+  );
 
   // Remove from integrationBlockHashes
   if (manifest.integrationBlockHashes && manifest.integrationBlockHashes[relativePath]) {
@@ -761,7 +766,7 @@ export function getSourcePathFromRelative(manifest, relativePath) {
   }
 
   // Check integrations - these might need special handling
-  if (manifest.integrations.includes(relativePath)) {
+  if (manifest.integrations.some(i => (resolveIntegrationFile(i) || i) === relativePath)) {
     // Integration files have different source paths
     const integrationMappings = {
       '.cursorrules': 'integrations/cursor/.cursorrules',
@@ -831,7 +836,8 @@ async function migrateToHashBasedTracking(projectPath, manifest) {
   }
 
   // Process integrations
-  for (const int of manifest.integrations) {
+  for (const intEntry of manifest.integrations) {
+    const int = resolveIntegrationFile(intEntry) || intEntry;
     const fullPath = join(projectPath, int);
 
     const hashInfo = computeFileHash(fullPath);
@@ -1148,6 +1154,27 @@ function checkIntegrationFiles(manifest, projectPath, msg) {
     // Report status - use all installed standards as the total
     const totalTrackable = standardsFiles.length;
 
+    // Index-mode blocks deliberately do NOT enumerate standards (XSPEC-358 R1);
+    // grepping for each name reports a false failure and points at `uds update`,
+    // which regenerates the identical block. Assert the declared count instead.
+    const declaredCount = parseStandardsIndexCount(content);
+    if (declaredCount !== null) {
+      if (declaredCount === totalTrackable) {
+        console.log(chalk.green(`  ✓ ${toolFile}:`));
+        console.log(chalk.gray(`    ${msg.standardsIndexPresent}`));
+        console.log(chalk.gray(`    ${msg.standardsIndexCount
+          ? msg.standardsIndexCount.replace('{count}', declaredCount)
+          : `Index declares ${declaredCount} standards (matches manifest)`}`));
+      } else {
+        console.log(chalk.yellow(`  ⚠ ${toolFile}:`));
+        console.log(chalk.yellow(`    ${msg.standardsIndexCountMismatch
+          ? msg.standardsIndexCountMismatch.replace('{declared}', declaredCount).replace('{actual}', totalTrackable)
+          : `Index declares ${declaredCount} standards but the manifest has ${totalTrackable}`}`));
+        hasIssues = true;
+      }
+      continue;
+    }
+
     if (hasStandardsIndex && missingStandards.length === 0) {
       console.log(chalk.green(`  ✓ ${toolFile}:`));
       console.log(chalk.gray(`    ${msg.standardsIndexPresent}`));
@@ -1219,6 +1246,25 @@ function checkAgentsMdSync(manifest, projectPath, msg) {
   const content = readFileSync(agentsMdPath, 'utf-8');
   const installedStandards = (manifest.standards || []).map(s => basename(s));
 
+  // Same as the AI-tool integration check above: an index-mode block declares a
+  // count instead of listing names, so the name grep below cannot apply to it.
+  const declaredCount = parseStandardsIndexCount(content);
+  if (declaredCount !== null) {
+    const actual = installedStandards.length;
+    if (declaredCount === actual) {
+      console.log(chalk.green(`  ✓ AGENTS.md ${msg.standardsSynced || 'standards synced'} (${declaredCount})`));
+    } else {
+      console.log(chalk.yellow(`  ⚠ AGENTS.md ${msg.standardsOutOfSync || 'standards out of sync'} (${declaredCount} != ${actual})`));
+      console.log(chalk.gray(`    ${msg.runUpdateToSync || 'Run "uds update" to sync'}`));
+    }
+    const idxLineCount = content.split('\n').length;
+    if (idxLineCount > 150) {
+      console.log(chalk.yellow(`  ⚠ AGENTS.md ${msg.exceedsLineLimit || 'exceeds 150 line limit'} (${idxLineCount} lines)`));
+    }
+    console.log();
+    return;
+  }
+
   // Check standards listed in AGENTS.md vs manifest
   const aiYamlStandards = installedStandards.filter(s => s.endsWith('.ai.yaml'));
   let listedCount = 0;
@@ -1264,7 +1310,8 @@ function checkReferenceSync(manifest, projectPath, msg) {
 
   // Pre-scan: collect results for files that have references
   const results = [];
-  for (const integrationPath of manifest.integrations) {
+  for (const integrationEntry of manifest.integrations) {
+    const integrationPath = resolveIntegrationFile(integrationEntry) || integrationEntry;
     const fullPath = join(projectPath, integrationPath);
 
     if (!existsSync(fullPath)) continue;
@@ -1700,7 +1747,7 @@ function getFileStatusCounts(manifest, projectPath) {
     const allFiles = [
       ...manifest.standards.map(s => `.standards/${basename(s)}`),
       ...manifest.extensions.filter(e => typeof e === 'string').map(e => `.standards/${basename(e)}`),
-      ...manifest.integrations
+      ...manifest.integrations.map(i => resolveIntegrationFile(i) || i)
     ];
     for (const relativePath of allFiles) {
       const fullPath = join(projectPath, relativePath);

package/src/commands/config.js

@@ -49,6 +49,7 @@ import {
 } from '../utils/integration-generator.js';
 import { getMarketplaceSkillsInfo } from '../utils/github.js';
 import { regenerateIntegrations } from './update.js';
+import { mergeInstalledNames } from '../core/manifest.js';
 
 /**
  * Get localized message with fallback (for config-specific keys)
@@ -995,6 +996,7 @@ export async function runProjectConfiguration(options) {
                 manifest.skills.installations.push(inst);
               }
             }
+            manifest.skills.names = mergeInstalledNames(manifest.skills.names, skillResult);
             if (skillResult.allFileHashes) {
               manifest.skillHashes = { ...(manifest.skillHashes || {}), ...skillResult.allFileHashes };
             }
@@ -1031,6 +1033,7 @@ export async function runProjectConfiguration(options) {
                 manifest.commands.installations.push(inst);
               }
             }
+            manifest.commands.names = mergeInstalledNames(manifest.commands.names, cmdResult);
             if (cmdResult.allFileHashes) {
               manifest.commandHashes = { ...(manifest.commandHashes || {}), ...cmdResult.allFileHashes };
             }
@@ -1234,6 +1237,7 @@ async function handleSkillsConfiguration(manifest, projectPath, msgObj, common,
     } else {
       manifest.skills.installations.push(installations[0]);
     }
+    manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
     writeManifest(manifest, projectPath);
     return;
   }
@@ -1368,6 +1372,7 @@ async function handleSkillsConfiguration(manifest, projectPath, msgObj, common,
     // Update manifest - clear declined status for installed tools
     manifest.skills = manifest.skills || {};
     manifest.skills.installations = installations;
+    manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
     if (manifest.declinedFeatures?.skills) {
       manifest.declinedFeatures.skills = manifest.declinedFeatures.skills.filter(
         tool => !declinedToolsWithSupport.includes(tool)
@@ -1402,6 +1407,7 @@ async function handleSkillsConfiguration(manifest, projectPath, msgObj, common,
   // Update manifest
   manifest.skills = manifest.skills || {};
   manifest.skills.installations = installations;
+  manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
   writeManifest(manifest, projectPath);
 }
 
@@ -1465,6 +1471,7 @@ async function handleCommandsConfiguration(manifest, projectPath, msgObj, common
     } else {
       manifest.commands.installations.push(installations[0]);
     }
+    manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
     writeManifest(manifest, projectPath);
     return;
   }
@@ -1566,6 +1573,7 @@ async function handleCommandsConfiguration(manifest, projectPath, msgObj, common
     // Update manifest - clear declined status for installed tools
     manifest.commands = manifest.commands || {};
     manifest.commands.installations = declinedCommandsWithSupport;
+    manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
     if (manifest.declinedFeatures?.commands) {
       manifest.declinedFeatures.commands = manifest.declinedFeatures.commands.filter(
         tool => !declinedCommandsWithSupport.includes(tool)
@@ -1601,5 +1609,6 @@ async function handleCommandsConfiguration(manifest, projectPath, msgObj, common
   // Update manifest
   manifest.commands = manifest.commands || {};
   manifest.commands.installations = selectedAgents;
+  manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
   writeManifest(manifest, projectPath);
 }

package/src/commands/init.js

@@ -240,7 +240,21 @@ export async function initCommand(options) {
  * - Node.js projects: use husky
  * - Non-Node.js projects: write native .git/hooks/pre-commit
  */
-export async function setupHuskyHook(projectPath) {
+export async function setupHuskyHook(projectPath, { allowInTest = false } = {}) {
+  // 2026-07-30：本函式在跑測試時改寫了 universal-dev-standards 自己
+  // ——`npm install --save-dev husky`、改 package.json、建 .husky/pre-commit。
+  //
+  // 路徑是：測試呼叫 `initCommand({...})`（三個 init 測試檔都沒帶路徑、
+  // 也沒 mock child_process）→ `init.js` 取 `process.cwd()` → 走到這裡。
+  // 而下面那個 `.git` 是唯一的守衛，它只問「cwd 是不是一個 repo」：
+  //   從 `cli/` 跑 → cwd 沒有 .git → 提早 return，無害；
+  //   從 repo root 跑 → cwd **有** .git → 照跑，動到開發者自己的 repo。
+  // 同一批測試、不同 cwd，一個無害一個會寫檔。
+  //
+  // 守衛用顯式 opt-in 而非「偵測到測試就一律跳過」：`init.husky.test.js` 有十幾條
+  // 測試是**刻意**在暫存目錄裡驗這個函式的行為，一律跳過會把它們變成永遠通過的空測試。
+  if (process.env.VITEST && !allowInTest) return;
+
   const hasGit = existsSync(join(projectPath, '.git'));
   if (!hasGit) return;
 

package/src/commands/release.js

@@ -10,7 +10,7 @@
  */
 
 import chalk from 'chalk';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { execSync } from 'child_process';

package/src/commands/update.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { select, confirm as inquirerConfirm, checkbox, Separator } from '@inquirer/prompts';
 import { execSync } from 'child_process';
-import { existsSync, unlinkSync } from 'fs';
+import { existsSync, readFileSync, unlinkSync } from 'fs';
 import { join, basename } from 'path';
 import { readManifest, writeManifest, copyStandard, isInitialized } from '../utils/copier.js';
 import { getRepositoryInfo, getAllStandards, getStandardSource } from '../utils/registry.js';
@@ -11,7 +11,10 @@ import {
   writeIntegrationFile,
   getToolFilePath,
   writeAgentsMdSummary,
-  resolveContentModeForTool
+  resolveContentModeForTool,
+  generateIntegrationContent,
+  extractMarkedContent,
+  buildToolIntegrationConfig
 } from '../utils/integration-generator.js';
 import {
   calculateCategoriesFromStandards,
@@ -51,6 +54,8 @@ import {
 } from '../reconciler/index.js';
 import { restoreSingleFile } from './check.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
+import { resolveIntegrationFile } from '../core/constants.js';
+import { mergeInstalledNames } from '../core/manifest.js';
 
 /**
  * Determine the correct target directory for a standard file.
@@ -335,8 +340,12 @@ export async function updateCommand(options) {
   }
 
   // Handle --integrations-only option
+  // ⚠️ 這個分支在 --plan 檢查（見下）**之前**，所以必須自己處理 --plan——
+  //    否則 `--plan --integrations-only` 會靜默寫檔。2026-07-30 實測踩到：
+  //    以該組合驗證 XSPEC-358 的區塊變更時，它改了 machine-setup 的
+  //    CLAUDE.md 與 .standards/manifest.json，而旗標文件寫的是 "without executing"。
   if (options.integrationsOnly) {
-    await updateIntegrationsOnly(projectPath, manifest);
+    await updateIntegrationsOnly(projectPath, manifest, options);
     return;
   }
 
@@ -847,8 +856,9 @@ export async function updateCommand(options) {
     const fileName = basename(ext);
     allTrackedFiles.push(join('.standards', fileName));
   }
-  for (const int of (manifest.integrations || [])) {
-    const filePath = getToolFilePath(int);
+  for (const intEntry of (manifest.integrations || [])) {
+    // 兩種形狀都要能解出路徑（XSPEC-343 R1）
+    const filePath = resolveIntegrationFile(intEntry) || getToolFilePath(intEntry);
     if (filePath) {
       allTrackedFiles.push(filePath);
     }
@@ -951,6 +961,7 @@ export async function updateCommand(options) {
             ...(manifest.skills.installations || []),
             ...installSkills
           ];
+          manifest.skills.names = mergeInstalledNames(manifest.skills.names, skillResult);
 
           // Derive location from installations if not set
           if (!manifest.skills.location) {
@@ -987,6 +998,7 @@ export async function updateCommand(options) {
           // Update manifest version
           if (!manifest.skills) manifest.skills = {};
           manifest.skills.version = repoInfo.skills.version;
+          manifest.skills.names = mergeInstalledNames(manifest.skills.names, updateResult);
 
           // Derive location from installations if not set
           if (!manifest.skills.location && manifest.skills.installations?.length > 0) {
@@ -1028,6 +1040,7 @@ export async function updateCommand(options) {
             ...(manifest.commands.installations || []),
             ...installCommands
           ];
+          manifest.commands.names = mergeInstalledNames(manifest.commands.names, cmdResult);
 
           // Update command hashes for integrity tracking
           if (cmdResult.allFileHashes) {
@@ -1053,6 +1066,7 @@ export async function updateCommand(options) {
           // Update manifest version
           if (!manifest.commands) manifest.commands = {};
           manifest.commands.version = repoInfo.skills.version;
+          manifest.commands.names = mergeInstalledNames(manifest.commands.names, updateCmdResult);
 
           // Update command hashes for integrity tracking
           if (updateCmdResult.allFileHashes) {
@@ -1127,6 +1141,7 @@ export async function updateCommand(options) {
           manifest.skills.installed = true;
           manifest.skills.version = repoInfo.skills.version;
           manifest.skills.installations = [...(manifest.skills.installations || []), ...missingSkills];
+          manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
           if (result.allFileHashes) {
             if (!manifest.skillHashes) manifest.skillHashes = {};
             Object.assign(manifest.skillHashes, result.allFileHashes);
@@ -1144,6 +1159,7 @@ export async function updateCommand(options) {
           const result = await installSkillsToMultipleAgents(outdatedSkills, null, projectPath, skillsLocale);
           if (!manifest.skills) manifest.skills = {};
           manifest.skills.version = repoInfo.skills.version;
+          manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
           if (!manifest.skills.location && manifest.skills.installations?.length > 0) {
             const levels = manifest.skills.installations.map(s => s.level).filter(Boolean);
             const uniqueLevels = [...new Set(levels)];
@@ -1168,6 +1184,7 @@ export async function updateCommand(options) {
           manifest.commands.installed = true;
           manifest.commands.version = repoInfo.skills.version;
           manifest.commands.installations = [...(manifest.commands.installations || []), ...missingCommands];
+          manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
           if (result.allFileHashes) {
             if (!manifest.commandHashes) manifest.commandHashes = {};
             replaceCommandHashesForUpdatedAgents(manifest.commandHashes, result.allFileHashes);
@@ -1185,6 +1202,7 @@ export async function updateCommand(options) {
           const result = await installCommandsToMultipleAgents(outdatedCommands, null, projectPath, skillsLocale);
           if (!manifest.commands) manifest.commands = {};
           manifest.commands.version = repoInfo.skills.version;
+          manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
           if (result.allFileHashes) {
             if (!manifest.commandHashes) manifest.commandHashes = {};
             replaceCommandHashesForUpdatedAgents(manifest.commandHashes, result.allFileHashes);
@@ -1319,17 +1337,6 @@ export function regenerateIntegrations(projectPath, manifest) {
     return { success: true, updated: [], errors: [] };
   }
 
-  // Build installed standards list
-  const installedStandardsList = manifest.standards?.map(s => basename(s)) || [];
-
-  // Determine language setting
-  let commonLanguage = 'en';
-  if ((manifest.options?.output_language || manifest.options?.commit_language) === 'bilingual') {
-    commonLanguage = 'bilingual';
-  } else if ((manifest.options?.output_language || manifest.options?.commit_language) === 'traditional-chinese') {
-    commonLanguage = 'zh-tw';
-  }
-
   const results = {
     updated: [],
     errors: []
@@ -1345,19 +1352,8 @@ export function regenerateIntegrations(projectPath, manifest) {
       continue; // Skip if already generated (AGENTS.md sharing)
     }
 
-    // Resolve contentMode per tool based on tier
-    const savedMode = manifest.contentMode || 'auto';
-    const resolvedMode = resolveContentModeForTool(tool, savedMode);
-    const toolConfig = {
-      tool,
-      categories: ['anti-hallucination', 'commit-standards', 'code-review'],
-      language: commonLanguage,
-      installedStandards: installedStandardsList,
-      contentMode: resolvedMode.contentMode,
-      level: resolvedMode.level,
-      // Pass output_language for dynamic commit standards generation
-      outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english'
-    };
+    // Shared with the reconciler so both paths emit the identical block.
+    const toolConfig = buildToolIntegrationConfig(manifest, tool);
 
     const result = writeIntegrationFile(tool, toolConfig, projectPath);
     if (result.success) {
@@ -1392,7 +1388,7 @@ export function regenerateIntegrations(projectPath, manifest) {
   // Regenerate universal AGENTS.md if enabled and not already covered
   if (manifest.generateAgentsMd && !generatedFiles.has('AGENTS.md')) {
     const summaryConfig = {
-      installedStandards: installedStandardsList,
+      installedStandards: (manifest.standards || []).map(s => basename(s)),
       language: manifest.options?.display_language || 'en',
       outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english',
       standardOptions: manifest.options || {}
@@ -1422,7 +1418,7 @@ export function regenerateIntegrations(projectPath, manifest) {
  * @param {string} projectPath - Project path
  * @param {Object} manifest - Manifest object
  */
-async function updateIntegrationsOnly(projectPath, manifest) {
+async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
   const msg = t().commands.update;
 
   console.log(chalk.cyan(msg.updatingIntegrationsOnly));
@@ -1436,6 +1432,59 @@ async function updateIntegrationsOnly(projectPath, manifest) {
     return;
   }
 
+  // --plan：只比對、不寫任何檔（連 manifest 也不寫）。
+  // 這一段刻意不呼叫 regenerateIntegrations——那個函式會寫檔，
+  // 「先寫再還原」的作法在中途掛掉時會留下壞狀態，比沒有 dry-run 更糟。
+  if (options.plan) {
+    console.log(chalk.bold('=== Integration Plan (dry run — nothing is written) ==='));
+    const wouldChange = [];
+    const unchanged = [];
+    const seen = new Set();
+    for (const tool of aiTools) {
+      const targetFile = getToolFilePath(tool);
+      if (seen.has(targetFile)) continue;
+      seen.add(targetFile);
+      const savedMode = manifest.contentMode || 'auto';
+      const resolvedMode = resolveContentModeForTool(tool, savedMode);
+      const next = generateIntegrationContent({
+        tool,
+        categories: ['anti-hallucination', 'commit-standards', 'code-review'],
+        language: (manifest.options?.output_language || manifest.options?.commit_language) === 'bilingual'
+          ? 'bilingual'
+          : (manifest.options?.output_language || manifest.options?.commit_language) === 'traditional-chinese'
+            ? 'zh-tw' : 'en',
+        installedStandards: manifest.standards?.map((x) => basename(x)) || [],
+        contentMode: resolvedMode.contentMode,
+        level: resolvedMode.level,
+        outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english'
+      });
+      const full = join(projectPath, targetFile);
+      const current = existsSync(full) ? readFileSync(full, 'utf8') : '';
+      const format = targetFile.endsWith('.md') ? 'markdown' : 'plaintext';
+      const cur = extractMarkedContent(current, format).content || '';
+      // 比對正規化過的內容：只關心「受管區塊會不會變」，不關心尾端空白。
+      if (cur.trim() === String(next).trim()) {
+        unchanged.push(targetFile);
+      } else {
+        const delta = String(next).trim().length - cur.trim().length;
+        wouldChange.push(`${targetFile} (${delta >= 0 ? '+' : ''}${delta} bytes in the UDS block)`);
+      }
+    }
+    if (wouldChange.length > 0) {
+      console.log(chalk.yellow(`  ~ Would update (${wouldChange.length}):`));
+      for (const f of wouldChange) console.log(chalk.gray(`      ${f}`));
+    }
+    if (unchanged.length > 0) {
+      console.log(chalk.gray(`  = Unchanged (${unchanged.length}): ${unchanged.join(', ')}`));
+    }
+    console.log();
+    console.log(chalk.gray('  Also NOT written in plan mode: .standards/manifest.json'));
+    console.log(chalk.gray('  (a real run rewrites it — version, fileHashes, integrationBlockHashes,'));
+    console.log(chalk.gray('   and it normalises any standards entries stored as full paths)'));
+    console.log();
+    return;
+  }
+
   const spinner = ora(msg.regeneratingIntegrations).start();
 
   // Use reusable regeneration function
@@ -1698,6 +1747,7 @@ async function updateSkillsOnly(projectPath, manifest, options) {
   // Update manifest
   manifest.skills.version = latestVersion;
   manifest.skills.installations = skillsInstallations;
+  manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
 
   // Update skill hashes for integrity tracking
   if (result.allFileHashes) {
@@ -1804,6 +1854,7 @@ async function updateCommandsOnly(projectPath, manifest, options) {
     }
     return inst;
   });
+  manifest.commands.names = mergeInstalledNames(manifest.commands.names, result);
 
   // Update command hashes for integrity tracking
   if (result.allFileHashes) {

package/src/config/ai-agent-paths.js

@@ -147,11 +147,22 @@ export const AI_AGENT_PATHS = {
   'codex': {
     name: 'OpenAI Codex',
     tier: 'partial',
+    // Verified against the official docs 2026-07-23 (developers.openai.com/codex/skills):
+    // Codex discovers skills in $CWD/.agents/skills, parent directories, $REPO_ROOT/.agents/skills
+    // and $HOME/.agents/skills. Note the plural `.agents/`.
+    //
+    // These were previously '.codex/skills/' and '~/.codex/skills', which Codex never reads —
+    // a directory UDS invented. Skills installed there were invisible, which is why a
+    // behavioural probe against Codex failed while Codex itself was behaving correctly
+    // (see integrations/verification/codex/2026-07-23.md).
     skills: {
-      project: '.codex/skills/',
-      user: join(homedir(), '.codex', 'skills')
+      project: '.agents/skills/',
+      user: join(homedir(), '.agents', 'skills')
     },
     commands: null, // Uses system commands
+    // NOT verified. The official skills docs describe `agents/openai.yaml` as a file *inside*
+    // a skill directory, not a separate top-level agents location. Left as-is rather than
+    // guessed at: an unverified path fails silently, which is the failure mode being fixed above.
     agents: {
       project: '.codex/agents/',
       user: join(homedir(), '.codex', 'agents')
@@ -241,16 +252,27 @@ export const AI_AGENT_PATHS = {
   'antigravity': {
     name: 'Google Antigravity',
     tier: 'minimal',
-    skills: {
-      project: '.agent/skills/',
-      user: join(homedir(), '.gemini', 'antigravity', 'skills')
-    },
+    // Skills install path is UNVERIFIED against a real Antigravity CLI, so it is null:
+    // `supportsSkills && skills` is the install guard everywhere (init.js, init-flow.js,
+    // update.js, config.js), and a null `skills` makes it decline rather than write to a
+    // path the tool may never read.
+    //
+    // Two candidates conflict, and neither has been tested:
+    //   a) ~/.gemini/antigravity-cli/plugins/<name>/skills/  -- official plugin docs
+    //   b) .agent/skills/ + ~/.gemini/antigravity/skills     -- UDS's own 2026-02 spec,
+    //      written while Gemini CLI was still the product; Antigravity replaced it on
+    //      2026-06-18, so (b) inherits an assumption that may no longer hold.
+    //
+    // Installing to the wrong path fails SILENTLY -- the user sees a successful init and
+    // an assistant that never picks the skills up. Declining is the safer default until
+    // one candidate is confirmed. Tracked as XSPEC-355 OQ6.
+    skills: null,
     commands: null,
     agents: null,
     workflows: null,
     supportsMarketplace: false,
     fallbackSkillsPath: null,
-    supportsSkills: true, // Skills since Nov 2025
+    supportsSkills: true, // The tool does support skills; only our path for it is unverified.
     supportsTask: false,
     supportsAgents: false
   }
@@ -313,6 +335,24 @@ export function getCommandsDirForAgent(agent, level = 'project', projectPath = n
   return null;
 }
 
+/**
+ * Get the on-disk file extension used for an agent's slash commands.
+ *
+ * The command *name* (`commit`) and the installed *file* (`commit.toml` for
+ * Gemini CLI, `commit.md` for everyone else) are not the same string. Any code
+ * that maps one to the other must go through here — a hard-coded `.md` strip
+ * silently drops every Gemini command on the floor, and because the mismatch
+ * produces a well-formed name that simply never matches, nothing errors.
+ * (XSPEC-343 R2: 30 of machine-setup's 86 proposed deletions were exactly this.)
+ *
+ * @param {string} agent - Agent identifier
+ * @returns {string} Extension including the leading dot
+ */
+export function getCommandFileExtension(agent) {
+  const config = AI_AGENT_PATHS[agent];
+  return config?.commandFormat === 'toml' ? '.toml' : '.md';
+}
+
 /**
  * Get all agents that support skills installation
  * @returns {string[]} Array of agent identifiers

package/src/core/constants.js

@@ -523,4 +523,64 @@ export default {
   doesToolSupport,
   getToolFormat,
   getToolFileName
-};
+};
+
+/**
+ * `manifest.integrations` has been written in two shapes by two code paths:
+ * tool keys (`claude-code`) and file paths (`CLAUDE.md`, or even absolute).
+ * Three consumers read it with two different assumptions —
+ * desired-state-calculator expects tool keys, integration-uninstaller expects
+ * file names — so normalising to one shape fixes one and breaks the other.
+ *
+ * These two resolvers let every consumer accept either shape. Measured
+ * 2026-07-30: 20 of 21 adopter repos stored file names. (XSPEC-343 R1)
+ */
+
+/** Entry (tool key OR file path) → tool key, or null. */
+export function resolveToolKey(entry) {
+  if (typeof entry !== 'string' || entry.length === 0) return null;
+  if (SUPPORTED_AI_TOOLS[entry]) return entry;
+  const norm = entry.replace(/\\/g, '/');
+  for (const [key, cfg] of Object.entries(SUPPORTED_AI_TOOLS)) {
+    if (!cfg?.file) continue;
+    // Exact or path-suffix only. A bare basename match would let `MY-CLAUDE.md`
+    // or `CLAUDE.md.bak` pass as the managed integration file.
+    if (norm === cfg.file || norm.endsWith(`/${cfg.file}`)) return key;
+  }
+  return null;
+}
+
+/** Entry (tool key OR file path) → repo-relative integration file, or null. */
+export function resolveIntegrationFile(entry) {
+  const key = resolveToolKey(entry);
+  return key ? SUPPORTED_AI_TOOLS[key].file : null;
+}
+
+/**
+ * How the flat keys in `manifest.options` bind to registry option categories.
+ *
+ * The manifest stores selections flat — `{ workflow: 'github-flow',
+ * test_levels: [...] }` — while the registry nests them under a standard id and
+ * a category key, and the two names are not always the same word (`test_levels`
+ * vs `test_level`). The installer knew this mapping inline; the reconciler's
+ * desired-state calculator instead iterated `manifest.options` as if it were
+ * keyed by *standard id*, looked up a standard called `workflow`, found nothing,
+ * and skipped. It produced an empty desired option set for every adopter repo,
+ * so every installed option file diffed as "no longer in desired state" —
+ * including the ones the manifest explicitly selected. (XSPEC-343 R2)
+ *
+ * Keys with no entry here (`display_language`, `release_mode`, `coverage_model`)
+ * are behaviour settings that install no file.
+ */
+export const MANIFEST_OPTION_BINDINGS = [
+  { manifestKeys: ['workflow'], standardId: 'git-workflow', categoryKey: 'workflow' },
+  { manifestKeys: ['merge_strategy'], standardId: 'git-workflow', categoryKey: 'merge_strategy' },
+  { manifestKeys: ['output_language', 'commit_language'], standardId: 'commit-message', categoryKey: 'output_language' },
+  { manifestKeys: ['test_levels'], standardId: 'testing', categoryKey: 'test_level' }
+];
+
+/**
+ * Option files are installed flat, not nested by standard/category.
+ * (`installers/standards-installer.js` copies into `.standards/options`.)
+ */
+export const OPTIONS_INSTALL_DIR = '.standards/options';