universal-dev-standards 6.9.0 → 6.11.0

package/src/core/manifest.js

@@ -773,10 +773,48 @@ export function needsMigration(manifest) {
   if (!manifest) {
     return true;
   }
-  
+
   return manifest.version !== CURRENT_SCHEMA_VERSION;
 }
 
+/**
+ * Compare two `x.y.z` version strings numerically (not lexically — '3.10.0'
+ * must sort after '3.9.0'). Missing components count as 0.
+ * @returns {number} negative if a<b, 0 if equal, positive if a>b
+ */
+function compareSemverStrings(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa[i] || 0) - (pb[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Set `manifest.version` to the CLI's current schema version — never lower.
+ *
+ * XSPEC adopter-report Q1: five write sites across update.js/check.js/config.js
+ * each hardcoded a schema version literal ('3.1.0'/'3.2.0'/'3.3.0') instead of
+ * CURRENT_SCHEMA_VERSION. Every one of those literals predates a later schema
+ * bump, so running the operation on an already-current manifest (3.4.0)
+ * downgraded it back to whatever the literal said. This is the single place
+ * that decision is made: always move toward CURRENT_SCHEMA_VERSION, never
+ * away from it, even if a caller is ever fixed incompletely again.
+ *
+ * @param {Object} manifest - Manifest object (mutated in place)
+ */
+export function bumpManifestVersion(manifest) {
+  const current = manifest.version;
+  const isWellFormed = typeof current === 'string' && /^\d+\.\d+\.\d+$/.test(current);
+  if (!isWellFormed || compareSemverStrings(current, CURRENT_SCHEMA_VERSION) < 0) {
+    manifest.version = CURRENT_SCHEMA_VERSION;
+  }
+  // else: manifest.version is already at or ahead of CURRENT_SCHEMA_VERSION
+  // (e.g. a newer version written by a future CLI) — leave it alone.
+}
+
 /**
  * Get all AI tools from manifest
  * @param {Object} manifest - Manifest

package/src/flows/init-flow.js

@@ -242,6 +242,13 @@ export async function runInitFlow(options, detected, projectPath) {
   // Optional step — skippable by answering "n" or pressing Ctrl+C.
   await promptProjectContractStep(projectPath);
 
+  // XSPEC-418 R2: --claude-target is a flag, not an interactive question, but a
+  // user running `uds init --claude-target local` without `-y` still expects it
+  // honored while answering the rest of the prompts.
+  const integrationTargets = options.claudeTarget === 'local'
+    ? { 'claude-code': 'CLAUDE.local.md' }
+    : undefined;
+
   return {
     languages,
     frameworks,
@@ -253,6 +260,7 @@ export async function runInitFlow(options, detected, projectPath) {
     integrations,
     contentMode,
     generateAgentsMd,
-    releaseMode
+    releaseMode,
+    integrationTargets
   };
 }

package/src/generators/layered-claudemd.js

@@ -11,26 +11,35 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { mapStandardsToDirectories } from '../utils/directory-mapper.js';
+import { locateMarkerBlock } from '../utils/marker-locator.js';
 
 const UDS_BEGIN = '<!-- UDS:STANDARDS:BEGIN -->';
 const UDS_END = '<!-- UDS:STANDARDS:END -->';
 
 /**
  * Replace content between UDS markers, preserving content outside markers.
+ *
+ * XSPEC adopter-report Q5: same defect class as integration-generator.js —
+ * raw indexOf matched the marker text anywhere in the file, not only on a
+ * standalone line. Routed through the shared locateMarkerBlock so a sentence
+ * mentioning the marker is never mistaken for the real boundary. Ambiguity
+ * (two real marker pairs) throws AmbiguousMarkerError, which this function
+ * intentionally does not catch — a write must refuse rather than guess.
+ *
  * @param {string} existing - Existing file content
  * @param {string} newUdsContent - New UDS content to insert between markers
  * @returns {string} Updated content
  */
 function replaceUdsBlock(existing, newUdsContent) {
-  const beginIdx = existing.indexOf(UDS_BEGIN);
-  const endIdx = existing.indexOf(UDS_END);
+  const block = locateMarkerBlock(existing, { start: UDS_BEGIN, end: UDS_END });
 
-  if (beginIdx === -1 || endIdx === -1) {
+  if (!block) {
     // No markers found — append UDS block
     return existing + '\n\n' + wrapWithMarkers(newUdsContent);
   }
 
-  const before = existing.substring(0, beginIdx);
+  const { startIdx, endIdx } = block;
+  const before = existing.substring(0, startIdx);
   const after = existing.substring(endIdx + UDS_END.length);
   return before + wrapWithMarkers(newUdsContent) + after;
 }

package/src/i18n/messages.js

@@ -743,6 +743,9 @@ export const messages = {
         unchanged: 'unchanged',
         modified: 'modified',
         missing: 'missing',
+        retired: 'no longer shipped by UDS',
+        retiredHeader: '{count} tracked file(s) are gone because UDS stopped shipping them. That is the migration completed, not a fault:',
+        retiredHint: 'Run `uds update` to drop their manifest records. `--restore` cannot bring them back — there is no source upstream.',
         existsNoHash: 'exists, no hash',
         summary: 'Summary: {unchanged} unchanged, {modified} modified, {missing} missing',
         // Actions available
@@ -837,10 +840,17 @@ export const messages = {
         refSyncStatus: 'Reference Sync Status:',
         noRefsFound: 'No standard references found',
         refsNotInManifest: 'References not in manifest:',
-        standardsNotReferenced: 'Standards not referenced (optional):',
+        standardsNotReferenced: 'Standards with no "Reference:"/"參考:" line in this file (optional):',
         refsInSync: '{path}: references in sync ({count} refs)',
         noIntegrationRefs: 'No integration files with standard references found.',
         runSyncRefs: 'Run `uds update --sync-refs` to fix reference issues.',
+        runIntegrationsOnly: 'Run `uds update --integrations-only` to regenerate integration files.',
+        danglingRefs: 'references files that are not on disk:',
+        brokenMentions: 'mentions paths that do not exist in this project:',
+        brokenMentionsFix: 'These are usually outside the UDS block, left by an older install. UDS does not rewrite text it did not write — correct them by hand or delete the line.',
+        danglingRefsFix: 'Run `uds update --integrations-only` to regenerate them.',
+        commandsUntracked: '{count} installed command file(s) are covered by no hash — integrity is not checked for them',
+        commandsUntrackedFix: 'Run `uds update --commands` to record them again.',
         // CLI update
         checkingCliUpdates: 'Checking for CLI updates...',
         couldNotCheckUpdates: 'ℹ Could not check for CLI updates (offline mode)',
@@ -1020,6 +1030,7 @@ export const messages = {
         syncingIntegrations: 'Syncing integration files...',
         syncedIntegrations: 'Synced {count} integration files',
         prunedOrphanedBlockHashes: 'Pruned {count} orphaned integration hash(es): {files}',
+        droppedRetiredHashes: 'Dropped {count} manifest record(s) for files UDS no longer ships and that are already gone:',
         // Success
         updateSuccess: '✓ Standards updated successfully!',
         versionUpdated: 'Version: {current} → {latest}',
@@ -1047,6 +1058,7 @@ export const messages = {
         // Sync refs
         syncingRefs: 'Syncing integration references...',
         noIntegrationConfigs: '⚠ No integration configurations found in manifest.',
+        integrationConfigsBackfilled: 'Rebuilt integration config for {count} file(s) from the manifest.',
         integrationConfigsRequired: 'Integration configs are required for reference sync.',
         thisHappensWhen: 'This happens when:',
         oldVersion: '- The project was initialized with an older version of UDS',
@@ -1971,6 +1983,9 @@ export const messages = {
         unchanged: '未變更',
         modified: '已修改',
         missing: '遺失',
+        retired: 'UDS 已不再出貨',
+        retiredHeader: '有 {count} 個被追蹤的檔案不見了，原因是 UDS 已不再出貨。那是遷移完成的樣子，不是故障：',
+        retiredHint: '執行 `uds update` 清掉它們在 manifest 的紀錄。`--restore` 救不回來——上游已經沒有來源。',
         existsNoHash: '存在，無 hash',
         summary: '摘要：{unchanged} 未變更，{modified} 已修改，{missing} 遺失',
         // Actions available
@@ -2065,10 +2080,17 @@ export const messages = {
         refSyncStatus: '參考同步狀態：',
         noRefsFound: '找不到標準參考',
         refsNotInManifest: '未在 manifest 中的參考：',
-        standardsNotReferenced: '未參考的標準（選用）：',
+        standardsNotReferenced: '本檔案中沒有「Reference:」或「參考:」行提及的標準（選用）：',
         refsInSync: '{path}：參考已同步（{count} 個參考）',
         noIntegrationRefs: '找不到有標準參考的整合檔案。',
         runSyncRefs: '執行 `uds update --sync-refs` 修復參考問題。',
+        runIntegrationsOnly: '執行 `uds update --integrations-only` 重新產生整合檔案。',
+        danglingRefs: '引用了磁碟上不存在的檔案：',
+        brokenMentions: '提到了本專案裡不存在的路徑：',
+        brokenMentionsFix: '這些通常在 UDS 區塊之外，是舊版安裝留下的。UDS 不會改寫不是它寫的文字——請手動更正或刪掉那一行。',
+        danglingRefsFix: '執行 `uds update --integrations-only` 重新產生。',
+        commandsUntracked: '{count} 個已安裝的斜線命令沒有任何雜湊涵蓋——這些檔案的完整性沒有被檢查',
+        commandsUntrackedFix: '執行 `uds update --commands` 重新記錄。',
         // CLI update
         checkingCliUpdates: '正在檢查 CLI 更新...',
         couldNotCheckUpdates: 'ℹ 無法檢查 CLI 更新（離線模式）',
@@ -2245,6 +2267,7 @@ export const messages = {
         syncingIntegrations: '同步整合檔案中...',
         syncedIntegrations: '已同步 {count} 個整合檔案',
         prunedOrphanedBlockHashes: '已清除 {count} 個孤兒整合雜湊：{files}',
+        droppedRetiredHashes: '已清掉 {count} 筆 manifest 紀錄——這些檔案 UDS 已不再出貨，而且本來就已經不在了：',
         // Success
         updateSuccess: '✓ 標準更新成功！',
         versionUpdated: '版本：{current} → {latest}',
@@ -2272,6 +2295,7 @@ export const messages = {
         // Sync refs
         syncingRefs: '同步整合參考中...',
         noIntegrationConfigs: '⚠ manifest 中找不到整合設定。',
+        integrationConfigsBackfilled: '已從 manifest 重建 {count} 個整合檔的設定。',
         integrationConfigsRequired: '參考同步需要整合設定。',
         thisHappensWhen: '這會發生在：',
         oldVersion: '- 專案使用較舊版本的 UDS 初始化',
@@ -3211,6 +3235,9 @@ export const messages = {
         unchanged: '未更改',
         modified: '已修改',
         missing: '缺失',
+        retired: 'UDS 已不再发布',
+        retiredHeader: '有 {count} 个被追踪的文件不见了，原因是 UDS 已不再发布。那是迁移完成的样子，不是故障：',
+        retiredHint: '执行 `uds update` 清掉它们在 manifest 的记录。`--restore` 救不回来——上游已经没有来源。',
         existsNoHash: '存在，无哈希',
         summary: '摘要：{unchanged} 未更改，{modified} 已修改，{missing} 缺失',
         // Actions available
@@ -3305,10 +3332,17 @@ export const messages = {
         refSyncStatus: '参考同步状态：',
         noRefsFound: '未找到标准引用',
         refsNotInManifest: 'manifest 中无引用：',
-        standardsNotReferenced: '未引用的标准（可选）：',
+        standardsNotReferenced: '本文件中没有"Reference:"或"參考:"行提及的标准（可选）：',
         refsInSync: '{path}：引用已同步（{count} 个引用）',
         noIntegrationRefs: '未找到包含标准引用的集成文件。',
         runSyncRefs: '执行 `uds update --sync-refs` 修复引用问题。',
+        runIntegrationsOnly: '执行 `uds update --integrations-only` 重新生成集成文件。',
+        danglingRefs: '引用了磁盘上不存在的文件：',
+        brokenMentions: '提到了本项目里不存在的路径：',
+        brokenMentionsFix: '这些通常在 UDS 区块之外，是旧版安装留下的。UDS 不会改写不是它写的文字——请手动更正或删掉那一行。',
+        danglingRefsFix: '执行 `uds update --integrations-only` 重新生成。',
+        commandsUntracked: '{count} 个已安装的斜杠命令没有任何哈希覆盖——这些文件的完整性没有被检查',
+        commandsUntrackedFix: '执行 `uds update --commands` 重新记录。',
         // CLI update
         checkingCliUpdates: '检查 CLI 更新...',
         couldNotCheckUpdates: 'ℹ 无法检查 CLI 更新（离线模式）',
@@ -3398,6 +3432,7 @@ export const messages = {
         syncingIntegrations: '正在同步集成文件...',
         syncedIntegrations: '已同步 {count} 个集成文件',
         prunedOrphanedBlockHashes: '已清除 {count} 个孤儿集成哈希：{files}',
+        droppedRetiredHashes: '已清掉 {count} 笔 manifest 记录——这些文件 UDS 已不再发布，而且本来就已经不在了：',
         // Success
         updateSuccess: '✓ 标准更新成功！',
         versionUpdated: '版本：{current} → {latest}',
@@ -3425,6 +3460,7 @@ export const messages = {
         // Sync refs
         syncingRefs: '正在同步集成引用...',
         noIntegrationConfigs: '⚠ manifest 中未找到集成配置。',
+        integrationConfigsBackfilled: '已从 manifest 重建 {count} 个集成文件的配置。',
         integrationConfigsRequired: '引用同步需要集成配置。',
         thisHappensWhen: '发生这种情况时：',
         oldVersion: '- 项目使用旧版 UDS 初始化',

package/src/installers/integration-installer.js

@@ -1,9 +1,9 @@
-import ora from 'ora';
+import { createSpinner } from '../utils/spinner.js';
 import { copyIntegration } from '../utils/copier.js';
 import {
   writeIntegrationFile,
   integrationFileExists,
-  getToolFilePath,
+  resolveIntegrationTargetFile,
   writeAgentsMdSummary,
   resolveContentModeForTool
 } from '../utils/integration-generator.js';
@@ -99,14 +99,16 @@ export async function installIntegrations(config, projectPath) {
   }
 
   // Start installation spinner
-  const intSpinner = ora(msg.generatingIntegrations).start();
+  const intSpinner = createSpinner(msg.generatingIntegrations).start();
 
   // Track generated files to handle AGENTS.md sharing (codex + opencode)
   const generatedFiles = new Set();
 
   for (const tool of integrations) {
     // Check if this file was already generated (for AGENTS.md sharing)
-    const targetFile = getToolFilePath(tool);
+    // XSPEC-418 R2: honors config.integrationTargets (set from --claude-target at
+    // init time) rather than always assuming each tool's default file.
+    const targetFile = resolveIntegrationTargetFile(tool, { integrationTargets: config.integrationTargets });
     if (generatedFiles.has(targetFile)) {
       // Skip - file already generated by another tool (e.g., codex generated AGENTS.md, skip opencode)
       continue;
@@ -129,7 +131,9 @@ export async function installIntegrations(config, projectPath) {
       contentMode: resolved.contentMode,
       level: resolved.level ?? level,
       // Pass output_language for dynamic commit standards generation
-      outputLanguage
+      outputLanguage,
+      // XSPEC-418 R2: forwarded so writeIntegrationFile resolves the actual target.
+      integrationTargets: config.integrationTargets
     };
 
     // Use dynamic generator
@@ -218,13 +222,14 @@ export async function generateClaudeMd(config, projectPath) {
 
   const msg = t().commands.init;
 
-  // Check if Claude Code is selected and CLAUDE.md doesn't exist
+  // Check if Claude Code is selected and its target file doesn't already exist
+  // XSPEC-418 R2: the target may be CLAUDE.local.md, not CLAUDE.md.
   const claudeCodeSelected = aiTools.includes('claude-code');
-  if (!claudeCodeSelected || integrationFileExists('claude-code', projectPath)) {
+  if (!claudeCodeSelected || integrationFileExists('claude-code', projectPath, { integrationTargets: config.integrationTargets })) {
     return { path: null, error: null };
   }
 
-  const claudeSpinner = ora(msg.generatingClaudeMd).start();
+  const claudeSpinner = createSpinner(msg.generatingClaudeMd).start();
 
   // Derive categories from installedStandards to avoid referencing non-installed standards
   const categories = installedStandards.length > 0
@@ -245,7 +250,9 @@ export async function generateClaudeMd(config, projectPath) {
     contentMode: claudeResolved.contentMode,
     level: claudeResolved.level ?? level,
     // Pass output_language for dynamic commit standards generation
-    outputLanguage
+    outputLanguage,
+    // XSPEC-418 R2
+    integrationTargets: config.integrationTargets
   };
 
   const result = writeIntegrationFile('claude-code', claudeConfig, projectPath);
@@ -285,7 +292,7 @@ export async function generateUniversalAgentsMd(config, integrationResults, proj
   }
 
   const msg = t().commands.init;
-  const spinner = ora(msg.generatingAgentsMd || 'Generating AGENTS.md...').start();
+  const spinner = createSpinner(msg.generatingAgentsMd || 'Generating AGENTS.md...').start();
 
   const outputLanguage = config.outputLanguage || config.commitLanguage ||
     config.standardOptions?.output_language || config.standardOptions?.commit_language ||

package/src/installers/manifest-installer.js

@@ -31,6 +31,10 @@ export function writeFinalManifest(config, results, projectPath) {
     extensions: results.extensions || [],
     integrations: results.integrations || [],
     integrationConfigs: results.manifestIntegrationConfigs || {},
+    // XSPEC-418 R2: only ever present when --claude-target local was chosen.
+    // Omitted entirely otherwise so a manifest with no override is byte-for-byte
+    // what it was before this feature existed (AC-5).
+    ...(config.integrationTargets ? { integrationTargets: config.integrationTargets } : {}),
     options: {
       display_language: config.displayLanguage || 'en',
       workflow: config.standardOptions?.workflow || null,

package/src/installers/skills-installer.js

@@ -13,7 +13,7 @@
  * @version 1.0.0
  */
 
-import ora from 'ora';
+import { createSpinner } from '../utils/spinner.js';
 import chalk from 'chalk';
 import {
   installSkillsToMultipleAgents,
@@ -115,7 +115,7 @@ function getSkillFiles() {
 export async function installSkills(skillsConfig, projectPath, messages, results) {
   // Modern unified multi-agent installation
   if (skillsConfig.needsInstall && skillsConfig.skillsInstallations?.length > 0) {
-    const skillSpinner = ora(messages.installingSkills).start();
+    const skillSpinner = createSpinner(messages.installingSkills).start();
 
     // Use new unified installer for multi-agent support
     const installResult = await installSkillsToMultipleAgents(
@@ -186,7 +186,7 @@ export async function installSkills(skillsConfig, projectPath, messages, results
  * @returns {Promise<void>}
  */
 async function installSkillsLegacy(skillsConfig, projectPath, messages, results) {
-  const skillSpinner = ora(messages.installingSkills).start();
+  const skillSpinner = createSpinner(messages.installingSkills).start();
 
   const skillFiles = getSkillFiles();
   let successCount = 0;
@@ -255,7 +255,7 @@ export async function installCommands(skillsConfig, projectPath, messages, resul
     return;
   }
 
-  const cmdSpinner = ora(messages.installingCommands || 'Installing slash commands...').start();
+  const cmdSpinner = createSpinner(messages.installingCommands || 'Installing slash commands...').start();
 
   const cmdResult = await installCommandsToMultipleAgents(
     skillsConfig.commandsInstallations,

package/src/installers/standards-installer.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import ora from 'ora';
+import { createSpinner } from '../utils/spinner.js';
 import { basename, join } from 'path';
 import {
   getAllStandards,
@@ -75,7 +75,7 @@ export async function installStandards(config, projectPath) {
   };
 
   // Start copying standards
-  const copySpinner = ora(msg.copyingStandards).start();
+  const copySpinner = createSpinner(msg.copyingStandards).start();
 
   // Copy standards based on format
   const formatsToUse = config.format === 'both' ? ['ai', 'human'] : [config.format];
@@ -113,7 +113,7 @@ export async function installStandards(config, projectPath) {
   const localeExtension = (config.displayLanguage === 'zh-tw' || config.displayLanguage === 'zh-cn') ? config.displayLanguage : null;
 
   if (config.languages.length > 0 || config.frameworks.length > 0 || localeExtension) {
-    const extSpinner = ora(msg.copyingExtensions).start();
+    const extSpinner = createSpinner(msg.copyingExtensions).start();
 
     for (const lang of config.languages) {
       if (EXTENSION_MAPPINGS[lang]) {

package/src/prompts/init.js

@@ -1,5 +1,5 @@
 import { select, checkbox, confirm as inquirerConfirm, Separator, input } from '@inquirer/prompts';
-import { existsSync, writeFileSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import chalk from 'chalk';
 import os from 'os';
@@ -1385,11 +1385,40 @@ export function suggestCommands(projectPath) {
   if (existsSync(p('Gemfile')))
     return { test: 'bundle exec rspec', lint: 'bundle exec rubocop', build: 'gem build *.gemspec', security: 'bundle audit' };
 
-  // C# — glob for .csproj / .sln
+  // C# — glob for .csproj / .sln.
+  //
+  // `.csproj` has named two incompatible build systems since 2017. An SDK-style
+  // project (`<Project Sdk="…">`, `<TargetFramework>`) builds with the `dotnet`
+  // CLI. An old-style one (`<TargetFrameworkVersion>`, no Sdk attribute) needs
+  // MSBuild and Visual Studio's targets, and handing it `dotnet build` produces
+  // `MSB4019: could not find Import project …Microsoft.WebApplication.targets`
+  // — reported 2026-09-16 from a .NET Framework 4.8 Web App, which also got
+  // `dotnet list package --vulnerable`, a command that silently reports nothing
+  // for a `packages.config` project because it only reads `PackageReference`.
+  //
+  // For the old style only `build` gets an answer. `dotnet format` requires an
+  // SDK-style project and there is no drop-in equivalent; test discovery
+  // depends on which runner the solution uses. The unknown-ecosystem branch
+  // below already returns blanks "so user fills them in", and a blank a human
+  // completes beats a command that looks authoritative and fails on first use.
   try {
     const files = readdirSync(projectPath);
-    if (files.some(f => f.endsWith('.csproj') || f.endsWith('.sln')))
-      return { test: 'dotnet test', lint: 'dotnet format --verify-no-changes', build: 'dotnet build', security: 'dotnet list package --vulnerable' };
+    const projectFiles = files.filter(f => f.endsWith('.csproj') || f.endsWith('.vbproj'));
+    if (projectFiles.length > 0 || files.some(f => f.endsWith('.sln'))) {
+      const oldStyle = projectFiles.some(f => {
+        try {
+          const xml = readFileSync(join(projectPath, f), 'utf-8');
+          if (/<Project[^>]*\sSdk\s*=/i.test(xml)) return false;
+          return /<TargetFrameworkVersion\s*>/i.test(xml);
+        } catch {
+          return false;
+        }
+      });
+
+      return oldStyle
+        ? { test: '', lint: '', build: 'msbuild /t:Build /p:Configuration=Release', security: '' }
+        : { test: 'dotnet test', lint: 'dotnet format --verify-no-changes', build: 'dotnet build', security: 'dotnet list package --vulnerable' };
+    }
   } catch {
     // ignore read errors
   }

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

@@ -13,6 +13,7 @@ import { join, relative } from 'path';
 import { readManifest } from '../core/manifest.js';
 import { computeFileHash, computeIntegrationBlockHash, normalizeLineEndings } from '../utils/hasher.js';
 import { SUPPORTED_AI_TOOLS, UDS_MARKERS } from '../core/constants.js';
+import { locateMarkerBlock, AmbiguousMarkerError } from '../utils/marker-locator.js';
 import { getSkillsDirForAgent, getCommandsDirForAgent, getCommandFileExtension } from '../config/ai-agent-paths.js';
 import { getSkillsSourceEntryNames, getAvailableCommandNames } from '../utils/skills-installer.js';
 
@@ -230,7 +231,21 @@ function scanIntegrations(state, projectPath) {
     const filePath = join(projectPath, toolConfig.file);
     if (!existsSync(filePath)) continue;
 
-    const blockHash = computeIntegrationBlockHash(filePath);
+    // XSPEC adopter-report Q5: this scan walks every configured tool's file
+    // in one pass to build a full picture of the project — one file with an
+    // ambiguous marker pair must not abort the whole scan. `uds check`'s
+    // dedicated block-integrity pass is what surfaces the ambiguity to the
+    // user explicitly, with line numbers; this scan just records "unknown".
+    let blockHash;
+    try {
+      blockHash = computeIntegrationBlockHash(filePath);
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        blockHash = null;
+      } else {
+        throw error;
+      }
+    }
     const fileHash = computeFileHash(filePath);
 
     state.integrations.set(toolConfig.file, {
@@ -543,7 +558,19 @@ function hasUDSMarkers(filePath, format) {
   try {
     const content = readFileSync(filePath, 'utf-8');
     const markers = UDS_MARKERS[format] || UDS_MARKERS.markdown;
-    return content.includes(markers.start) && content.includes(markers.end);
+    // XSPEC adopter-report Q5: `.includes()` matched the marker text
+    // anywhere in the file, including inside a sentence that merely mentions
+    // it — locateMarkerBlock requires a standalone, non-fenced line. An
+    // ambiguous file (two real marker lines) still "has UDS markers" for
+    // this boolean's purpose, so that is also true, not an error here.
+    try {
+      return locateMarkerBlock(content, markers) !== null;
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        return true;
+      }
+      throw error;
+    }
   } catch {
     return false;
   }

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

@@ -15,8 +15,15 @@ import {
   MANIFEST_OPTION_BINDINGS,
   OPTIONS_INSTALL_DIR
 } from '../core/constants.js';
+import {
+  resolveIntegrationTargetFile,
+  buildToolIntegrationConfig,
+  generateIntegrationContent,
+  extractMarkedContent
+} from '../utils/integration-generator.js';
 import { PathResolver } from '../core/paths.js';
 import { computeFileHash } from '../utils/hasher.js';
+import { createHash } from 'crypto';
 import {
   getSkillsDirForAgent,
   getCommandsDirForAgent,
@@ -261,6 +268,37 @@ function calculateExtensions(state, manifest) {
   }
 }
 
+/**
+ * Compute the block hash generation would produce for this tool right now,
+ * using the same builder (`buildToolIntegrationConfig`) and generator
+ * (`generateIntegrationContent`) `--apply`/`uds update` themselves use.
+ *
+ * Hashed the same way `computeIntegrationBlockHash` (hasher.js) hashes an
+ * actual on-disk file — extract the marker block, trim, sha256 — so the two
+ * are directly comparable. Never throws: generation can fail for reasons
+ * outside this module's control (an incomplete/mocked registry, a tool this
+ * process cannot resolve, etc.), and the correct response to "cannot compute
+ * an expected hash" is `null` — diffIntegrations already knows how to treat
+ * that the same as before this fix (always migrate_block), not to crash the
+ * whole state calculation over one tool.
+ *
+ * @param {Object} manifest
+ * @param {string} toolName
+ * @param {string} format
+ * @returns {string|null}
+ */
+function computeExpectedIntegrationBlockHash(manifest, toolName, format) {
+  try {
+    const config = { ...buildToolIntegrationConfig(manifest, toolName), format: manifest.format || 'ai' };
+    const generated = generateIntegrationContent({ ...config, tool: toolName });
+    const { content: blockContent } = extractMarkedContent(generated, format);
+    if (!blockContent) return null;
+    return `sha256:${createHash('sha256').update(blockContent).digest('hex')}`;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Calculate expected integration files.
  * For integrations we track the UDS marker block, not the entire file.
@@ -281,11 +319,22 @@ function calculateIntegrations(state, manifest) {
     const toolConfig = toolName ? SUPPORTED_AI_TOOLS[toolName] : null;
     if (!toolConfig) continue;
 
-    const relativePath = toolConfig.file;
+    // XSPEC-418 R2/R3: the desired path is the tool's ACTUAL target, not always
+    // its default file — a local-target claude-code install's desired state
+    // must say CLAUDE.local.md, or `--apply`/`--plan` (and their orphan
+    // detection) would treat that file as unmanaged and CLAUDE.md as desired.
+    const relativePath = resolveIntegrationTargetFile(toolName, manifest) || toolConfig.file;
 
     state.integrations.set(relativePath, {
       relativePath,
-      hash: null,  // Integration hashes are computed after generation
+      // XSPEC adopter-report Q6: this used to be a hardcoded `null` ("hashes
+      // are computed after generation"), which is why diffIntegrations could
+      // never tell "content already matches" from "content differs" and
+      // unconditionally produced migrate_block — `--plan` never converged,
+      // even immediately after `--apply`. Actually generating the content
+      // ahead of time (the same generation `--apply` itself runs) gives a
+      // real hash to compare against the actual file's block hash.
+      hash: computeExpectedIntegrationBlockHash(manifest, toolName, toolConfig.format),
       size: null,
       category: 'integration',
       sourcePath: null,  // Generated, not copied from source