universal-dev-standards 6.10.0 → 6.11.0

package/src/commands/check.js

@@ -12,7 +12,9 @@ import {
   computeFileHash,
   compareFileHash,
   hasFileHashes,
-  compareIntegrationBlockHash
+  compareIntegrationBlockHash,
+  computeIntegrationBlockHash,
+  pruneIntegrationFileHashes
 } from '../utils/hasher.js';
 import { downloadFromGitHub, getMarketplaceSkillsInfo } from '../utils/github.js';
 import {
@@ -30,7 +32,9 @@ import {
   findBrokenPathMentions,
   compareStandardsWithReferences
 } from '../utils/reference-sync.js';
-import { extractMarkedContent, getToolFilePath, parseStandardsIndexCount, writeIntegrationFile } from '../utils/integration-generator.js';
+import { extractMarkedContent, resolveIntegrationTargetFile, parseStandardsIndexCount, writeIntegrationFile } from '../utils/integration-generator.js';
+import { AmbiguousMarkerError } from '../utils/marker-locator.js';
+import { bumpManifestVersion } from '../core/manifest.js';
 import { INTEGRATION_MAPPINGS } from '../installers/integration-installer.js';
 import { getToolFormat } from '../core/constants.js';
 import { checkForUpdates } from '../utils/npm-registry.js';
@@ -137,6 +141,19 @@ function performFileIntegrityCheck(projectPath, manifest, msg) {
   if (hasFileHashes(manifest)) {
     // Hash-based integrity check
     for (const [relativePath, hashInfo] of Object.entries(manifest.fileHashes)) {
+      // XSPEC-418 R6 gap 2: a manifest written before this fix can still
+      // carry a whole-file entry for a path that is ALSO tracked by its UDS
+      // block (integrationBlockHashes) — the pruning added for R6 only runs
+      // on a write (uds update / check --restore / --migrate), so a project
+      // that has not run one of those yet stayed red on `uds check --ci`
+      // forever, for content outside the block that the block check itself
+      // says is fine. This is a READ-time skip — it does not touch the
+      // manifest, so a plain `uds check` alone cannot fix the underlying
+      // stale entry; the write paths still do that (see
+      // pruneIntegrationFileHashes in hasher.js).
+      if (manifest.integrationBlockHashes && relativePath in manifest.integrationBlockHashes) {
+        continue;
+      }
       const fullPath = join(projectPath, relativePath);
       const status = compareFileHash(fullPath, hashInfo);
 
@@ -401,12 +418,38 @@ export async function checkCommand(options = {}) {
   // Check Commands integrity if commandHashes exist
   checkCommandsIntegrity(manifest, projectPath, msg);
 
+  // XSPEC adopter-report Q3: neither of the two checks above (content-hash
+  // integrity) says anything about an installed Skills/Commands version
+  // being behind the latest UDS release — that was only ever computed by
+  // `uds update --plan --skills`/`--commands`. A plain `uds check` gave no
+  // signal at all that `uds update --skills` had anything to do.
+  checkSkillsCommandsVersionStaleness(manifest, projectPath, msg);
+
   // Check Integration blocks integrity if integrationBlockHashes exist
-  checkIntegrationBlocksIntegrity(manifest, projectPath, msg);
+  // XSPEC-418 R1: the return value used to be discarded, so a removed/modified
+  // UDS block never affected the final verdict below — `uds check --ci` printed
+  // "compliant" and exited 0 with a visible ✗ still on screen.
+  const integrationBlockStatus = checkIntegrationBlocksIntegrity(manifest, projectPath, msg);
 
   // Handle --restore option
   if (options.restore) {
-    await restoreFiles(projectPath, manifest, [...fileStatus.modified, ...fileStatus.missing]);
+    // XSPEC-418 R6 gap 1: integration files no longer live in `fileHashes`
+    // at all (that was the point of R6), so `fileStatus` — built entirely
+    // from `fileHashes` — never contains them any more. Without this,
+    // `--restore` silently did nothing for a damaged UDS block: it
+    // regenerated zero files and printed "Restored 0 file(s)" while the
+    // block-modified/markers-removed content sat untouched.
+    // `restoreSingleFile`'s integration-file branch (`manifest.integrationConfigs`)
+    // does not depend on fileHashes, so feeding these paths in is enough —
+    // it already regenerates just the block and leaves everything else alone.
+    const integrationFilesToRestore = [
+      ...integrationBlockStatus.modified,
+      ...integrationBlockStatus.noMarkers,
+      ...integrationBlockStatus.missing
+    ];
+    await restoreFiles(projectPath, manifest, [
+      ...new Set([...fileStatus.modified, ...fileStatus.missing, ...integrationFilesToRestore])
+    ]);
     return;
   }
 
@@ -470,8 +513,15 @@ export async function checkCommand(options = {}) {
   displayWorkflowStatus(projectPath);
 
   // Final status
+  // XSPEC-418 R1: integration block problems (UDS markers removed, block
+  // modified, or the tracked file missing) now feed the verdict — they used to
+  // be checked and printed above, then silently dropped here.
   const allGood = fileStatus.missing.length === 0 &&
-                  fileStatus.modified.length === 0;
+                  fileStatus.modified.length === 0 &&
+                  integrationBlockStatus.modified.length === 0 &&
+                  integrationBlockStatus.missing.length === 0 &&
+                  integrationBlockStatus.noMarkers.length === 0 &&
+                  integrationBlockStatus.ambiguous.length === 0;
   if (allGood) {
     console.log(chalk.green(msg.projectCompliant));
   } else {
@@ -584,6 +634,11 @@ async function interactiveMode(projectPath, manifest, fileStatus, msg) {
   }
 
   if (manifestUpdated) {
+    // XSPEC-418 R6: interactive mode still has a "keep current content" branch
+    // that calls the whole-file updateFileHash(); if issue.file happens to be
+    // an integration file left in fileHashes by an older CLI, this is the
+    // write point that stops it from surviving another round.
+    pruneIntegrationFileHashes(manifest);
     writeManifest(manifest, projectPath);
     console.log(chalk.green(msg.manifestUpdated));
     console.log();
@@ -701,6 +756,9 @@ async function restoreFiles(projectPath, manifest, files) {
   }
 
   // Update manifest
+  // XSPEC-418 R6: catches any stale whole-file entry for an integration file
+  // this particular restore run didn't touch, not just the ones it did.
+  pruneIntegrationFileHashes(manifest);
   writeManifest(manifest, projectPath);
   console.log(chalk.gray(`  ${msg.manifestUpdatedShort}`));
   console.log();
@@ -728,7 +786,13 @@ export async function restoreSingleFile(projectPath, manifest, relativePath, msg
       installedStandards: genConfig.installedStandards || manifest.standards || []
     }, projectPath);
     if (result.success) {
-      updateFileHash(projectPath, manifest, relativePath);
+      // XSPEC-418 R6: this rewrites the UDS block, so the BLOCK hash is what
+      // must be refreshed — not a whole-file hash. Restoring used to call
+      // updateFileHash() here, which recorded the whole file (block +
+      // whatever the adopter wrote outside it) while leaving the stale block
+      // hash untouched; the next `uds check` then reported "UDS block
+      // modified" for a block that had just been correctly restored.
+      updateIntegrationBlockHash(manifest, relativePath, result.blockHashInfo);
       console.log(chalk.green(`  ✓ ${relativePath}: ${msg.restored}`));
       return true;
     }
@@ -750,7 +814,32 @@ export async function restoreSingleFile(projectPath, manifest, relativePath, msg
     // Integration file - copy to root
     const result = await copyIntegration(sourcePath, relativePath, projectPath);
     if (result.success) {
-      updateFileHash(projectPath, manifest, relativePath);
+      // XSPEC-418 R6: same rule as the genConfig branch above — track the
+      // block, not the whole file. This legacy static-copy fallback has no
+      // blockHashInfo returned to it, so compute one from what was just
+      // written; a template with no UDS markers at all (computeIntegration
+      // BlockHash returns null) falls back to the old whole-file behaviour,
+      // since there is no block to track instead.
+      // XSPEC adopter-report Q5: the file was just overwritten wholesale by
+      // copyIntegration (a full template copy, not a marker-preserving
+      // merge), so an ambiguous marker pair here cannot be this restore's
+      // own doing — fall back to whole-file hashing rather than fail a
+      // restore that already succeeded on disk.
+      let blockHashInfo;
+      try {
+        blockHashInfo = computeIntegrationBlockHash(join(projectPath, relativePath));
+      } catch (error) {
+        if (error instanceof AmbiguousMarkerError) {
+          blockHashInfo = null;
+        } else {
+          throw error;
+        }
+      }
+      if (blockHashInfo) {
+        updateIntegrationBlockHash(manifest, relativePath, blockHashInfo);
+      } else {
+        updateFileHash(projectPath, manifest, relativePath);
+      }
       console.log(chalk.green(`  ✓ ${relativePath}: ${msg.restored}`));
       return true;
     } else {
@@ -770,6 +859,30 @@ export async function restoreSingleFile(projectPath, manifest, relativePath, msg
   }
 }
 
+/**
+ * Update an integration file's UDS BLOCK hash in the manifest — not its
+ * whole-file hash (XSPEC-418 R6). Also drops any whole-file `fileHashes`
+ * entry for the same path, so restoring an integration file can never leave
+ * both records behind at once.
+ *
+ * @param {Object} manifest - Manifest object (mutated in place)
+ * @param {string} relativePath - Path as UDS reports it
+ * @param {Object|null|undefined} blockHashInfo - `{ blockHash, blockSize, fullHash, fullSize }`,
+ *   e.g. from `writeIntegrationFile`'s result or `computeIntegrationBlockHash`
+ * @returns {boolean} Whether a block hash was recorded
+ */
+export function updateIntegrationBlockHash(manifest, relativePath, blockHashInfo) {
+  if (!blockHashInfo) return false;
+  const normalizedPath = relativePath.replace(/\\/g, '/');
+  if (!manifest.integrationBlockHashes) manifest.integrationBlockHashes = {};
+  manifest.integrationBlockHashes[normalizedPath] = {
+    ...blockHashInfo,
+    installedAt: new Date().toISOString()
+  };
+  if (manifest.fileHashes) delete manifest.fileHashes[normalizedPath];
+  return true;
+}
+
 /**
  * Update file hash in manifest
  */
@@ -918,21 +1031,54 @@ async function migrateToHashBasedTracking(projectPath, manifest) {
     }
   }
 
-  // Process integrations
+  // Process integrations — tracked by their UDS BLOCK hash, not a whole-file
+  // hash (XSPEC-418 R6). This loop used to write the whole file into the same
+  // `fileHashes` map as standards/extensions above, which is the same defect
+  // as every other write site R6 fixes, just reached by `--migrate` instead
+  // of a normal update: any content the adopter had outside the block then
+  // read as "modified" by standards-file integrity, contradicting the block
+  // check in the same `uds check` run.
+  const integrationBlockHashes = { ...(manifest.integrationBlockHashes || {}) };
   for (const intEntry of manifest.integrations) {
     const int = resolveIntegrationFile(intEntry) || intEntry;
     const fullPath = join(projectPath, int);
 
-    const hashInfo = computeFileHash(fullPath);
-    if (hashInfo) {
-      fileHashes[int] = { ...hashInfo, installedAt: now };
+    // XSPEC adopter-report Q5: this is a read-only manifest migration over
+    // every tracked integration file at once — one file with an ambiguous
+    // marker pair must not abort migrating the rest. It is simply left
+    // without a block hash, same as a file with no markers at all; `uds
+    // check`'s own block-integrity pass (below) is what surfaces the
+    // ambiguity to the user, with line numbers.
+    let blockHashInfo;
+    try {
+      blockHashInfo = computeIntegrationBlockHash(fullPath);
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        blockHashInfo = null;
+      } else {
+        throw error;
+      }
+    }
+    if (blockHashInfo) {
+      integrationBlockHashes[int] = { ...blockHashInfo, installedAt: now };
       count++;
+    } else {
+      // No UDS markers found (plaintext template with none, or a file the
+      // adopter fully rewrote) — fall back to whole-file tracking, same as
+      // before this fix, rather than silently tracking nothing.
+      const hashInfo = computeFileHash(fullPath);
+      if (hashInfo) {
+        fileHashes[int] = { ...hashInfo, installedAt: now };
+        count++;
+      }
     }
   }
 
   // Update manifest
   manifest.fileHashes = fileHashes;
-  manifest.version = '3.1.0';
+  manifest.integrationBlockHashes = integrationBlockHashes;
+  bumpManifestVersion(manifest);
+  pruneIntegrationFileHashes(manifest);
   writeManifest(manifest, projectPath);
 
   console.log(chalk.green(msg.migratedCount.replace('{count}', count)));
@@ -1220,7 +1366,9 @@ function checkIntegrationFiles(manifest, projectPath, msg) {
   // verdict — the tools that share it are named on the line instead.
   const toolsByFile = new Map();
   for (const tool of manifest.aiTools) {
-    const file = getToolFilePath(tool);
+    // XSPEC-418 R3: check must inspect the actual target file (e.g. CLAUDE.local.md),
+    // not the tool's hardcoded default.
+    const file = resolveIntegrationTargetFile(tool, manifest);
     if (!file) continue;
     if (!toolsByFile.has(file)) toolsByFile.set(file, []);
     toolsByFile.get(file).push(tool);
@@ -1251,7 +1399,20 @@ function checkIntegrationFiles(manifest, projectPath, msg) {
 
     // Check for standards index marker
     const format = getToolFormat(tool);
-    const { content: markedContent } = extractMarkedContent(content, format);
+    let markedContent;
+    try {
+      ({ content: markedContent } = extractMarkedContent(content, format));
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        // XSPEC adopter-report Q5: report explicitly with line numbers
+        // instead of guessing which marker pair is real, or silently
+        // treating the file as if it had no UDS block at all.
+        console.log(chalk.red(`  ✗ ${toolFile}: ${error.message}`));
+        hasIssues = true;
+        continue;
+      }
+      throw error;
+    }
     const hasStandardsIndex = markedContent.length > 0 ||
       content.includes('Standards Index') ||
       content.includes('Standards Compliance');
@@ -1607,6 +1768,59 @@ async function checkCliVersion(bundledVersion) {
 // Enhanced Integrity Check Functions (v3.3.0+)
 // ============================================================
 
+/**
+ * Warn when an installed Skills or Commands version is behind the latest
+ * UDS release. This is deliberately modeled on the existing top-level
+ * "Version: X → Y ⚠" row (see the `hasUpdate` check in the summary
+ * dashboard below) rather than on `checkIntegrationBlocksIntegrity`
+ * (XSPEC-418 R1): a version simply being behind the latest release is
+ * ambient, expected state until the adopter chooses to update — not a
+ * compliance defect the way a modified/missing/ambiguous UDS block is — so
+ * it is reported but, unlike a block problem, does not fail `--ci`.
+ *
+ * Skills staleness is read per-installation from what is actually on disk
+ * (`getInstalledSkillsInfoForAgent`), the same source `uds update --plan
+ * --skills` uses, because different agents/levels can be out of sync
+ * independently. Commands have no per-installation version on disk (only a
+ * file count), so Commands staleness is read from the one version the
+ * manifest itself records (`manifest.commands.version`).
+ * // implements XSPEC adopter-report Q3
+ *
+ * @param {Object} manifest
+ * @param {string} projectPath
+ * @param {Object} msg - Localized messages (unused today; kept for symmetry
+ *   with the other Enhanced Integrity Check functions, which all take one)
+ */
+function checkSkillsCommandsVersionStaleness(manifest, projectPath, msg) { // eslint-disable-line no-unused-vars
+  const repoInfo = getRepositoryInfo();
+  const latestVersion = repoInfo.skills.version;
+  const stale = [];
+
+  const skillsInstallations = (manifest.skills?.installations || []).filter((i) => i.level !== 'marketplace');
+  for (const inst of skillsInstallations) {
+    const info = getInstalledSkillsInfoForAgent(inst.agent, inst.level, projectPath);
+    const current = info?.version;
+    if (current && current !== latestVersion) {
+      stale.push(`${getAgentDisplayName(inst.agent)} (${inst.level}): Skills v${current} → v${latestVersion}`);
+    }
+  }
+
+  if (manifest.commands?.installed && (manifest.commands?.installations || []).length > 0) {
+    const current = manifest.commands.version;
+    if (current && current !== latestVersion) {
+      stale.push(`Commands: v${current} → v${latestVersion}`);
+    }
+  }
+
+  if (stale.length === 0) return;
+
+  for (const line of stale) {
+    console.log(chalk.yellow(`  ⚠ ${line}`));
+  }
+  console.log(chalk.gray('    Run `uds update --plan --skills` / `--commands` for details, then `--apply` to update.'));
+  console.log();
+}
+
 /**
  * Check Skills files integrity against stored hashes
  * @param {Object} manifest - Manifest object
@@ -1789,19 +2003,19 @@ export function checkCommandsIntegrity(manifest, projectPath, msg) {
  * @param {Object} manifest - Manifest object
  * @param {string} projectPath - Project root path
  * @param {Object} msg - Localized messages
- * @returns {Object} Status { unchanged: [], modified: [], missing: [], noMarkers: [] }
+ * @returns {Object} Status { unchanged: [], modified: [], missing: [], noMarkers: [], ambiguous: [] }
  */
 function checkIntegrationBlocksIntegrity(manifest, projectPath, msg) {
   const blockHashes = manifest.integrationBlockHashes;
 
   // Skip if no block hashes tracked
   if (!blockHashes || Object.keys(blockHashes).length === 0) {
-    return { unchanged: [], modified: [], missing: [], noMarkers: [], tracked: false };
+    return { unchanged: [], modified: [], missing: [], noMarkers: [], ambiguous: [], tracked: false };
   }
 
   console.log(chalk.cyan(msg.integrationBlocksCheck || 'Integration UDS Block Integrity'));
 
-  const status = { unchanged: [], modified: [], missing: [], noMarkers: [], tracked: true };
+  const status = { unchanged: [], modified: [], missing: [], noMarkers: [], ambiguous: [], tracked: true };
 
   for (const [filePath, hashInfo] of Object.entries(blockHashes)) {
     const fullPath = join(projectPath, filePath);
@@ -1813,7 +2027,21 @@ function checkIntegrationBlocksIntegrity(manifest, projectPath, msg) {
     }
 
     // Compare block hash
-    const blockStatus = compareIntegrationBlockHash(fullPath, hashInfo);
+    // XSPEC adopter-report Q5: a file with two real START or END marker
+    // lines is not "modified" and not "no markers" — it is ambiguous, and
+    // the whole point of this fix is to report that explicitly (with line
+    // numbers) instead of silently picking one and guessing.
+    let blockStatus;
+    try {
+      blockStatus = compareIntegrationBlockHash(fullPath, hashInfo);
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        status.ambiguous.push(filePath);
+        console.log(chalk.red(`  ✗ ${filePath}: ${error.message}`));
+        continue;
+      }
+      throw error;
+    }
 
     switch (blockStatus) {
       case 'unchanged':
@@ -1835,17 +2063,21 @@ function checkIntegrationBlocksIntegrity(manifest, projectPath, msg) {
   }
 
   // Summary
-  if (status.modified.length === 0 && status.missing.length === 0 && status.noMarkers.length === 0) {
+  if (status.modified.length === 0 && status.missing.length === 0 && status.noMarkers.length === 0 && status.ambiguous.length === 0) {
     console.log(chalk.green(`  ✓ ${msg.allBlocksIntact || 'All UDS blocks intact'} (${status.unchanged.length} files)`));
     console.log(chalk.gray(`    ${msg.userContentPreserved || 'User customizations outside UDS blocks are preserved'}`));
   } else {
     console.log(chalk.gray(`  ${(msg.blocksIntegritySummary || '{unchanged} intact, {modified} modified, {missing} missing')
       .replace('{unchanged}', status.unchanged.length)
       .replace('{modified}', status.modified.length)
-      .replace('{missing}', status.missing.length + status.noMarkers.length)}`));
+      .replace('{missing}', status.missing.length + status.noMarkers.length + status.ambiguous.length)}`));
 
     if (status.modified.length > 0 || status.noMarkers.length > 0) {
-      console.log(chalk.yellow(`    ${msg.runUpdateIntegrations || 'Run "uds update --integrations-only" to restore UDS content'}`));
+      // XSPEC-418 R6 gap 1: `uds check --restore` now regenerates just the
+      // UDS block for these files too (it used to do nothing for them — see
+      // the --restore handler above), so it is named alongside `uds update
+      // --integrations-only` rather than as a second-choice remedy.
+      console.log(chalk.yellow(`    ${msg.runUpdateIntegrations || 'Run "uds check --restore" or "uds update --integrations-only" to restore UDS content'}`));
     }
   }
 

package/src/commands/config.js

@@ -45,11 +45,11 @@ import {
 import { displayLanguageToLocale } from '../utils/locale.js';
 import {
   writeIntegrationFile,
-  getToolFilePath
+  resolveIntegrationTargetFile
 } from '../utils/integration-generator.js';
 import { getMarketplaceSkillsInfo } from '../utils/github.js';
 import { regenerateIntegrations } from './update.js';
-import { mergeInstalledNames } from '../core/manifest.js';
+import { mergeInstalledNames, bumpManifestVersion } from '../core/manifest.js';
 
 /**
  * Get localized message with fallback (for config-specific keys)
@@ -667,13 +667,16 @@ export async function runProjectConfiguration(options) {
       // Remove integration files for removed tools
       const spinner = createSpinner(msgObj.removingIntegrations).start();
       for (const tool of result.tools) {
-        const filePath = join(projectPath, getToolFilePath(tool));
+        // XSPEC-418 R3: remove the file this tool actually targets (e.g.
+        // CLAUDE.local.md), not always its hardcoded default.
+        const removedToolFile = resolveIntegrationTargetFile(tool, manifest);
+        const filePath = join(projectPath, removedToolFile);
         if (existsSync(filePath)) {
           try {
             unlinkSync(filePath);
-            console.log(chalk.gray(`  ${msgObj.removed}: ${getToolFilePath(tool)}`));
+            console.log(chalk.gray(`  ${msgObj.removed}: ${removedToolFile}`));
           } catch {
-            console.log(chalk.yellow(`  ${msgObj.couldNotRemove}: ${getToolFilePath(tool)}`));
+            console.log(chalk.yellow(`  ${msgObj.couldNotRemove}: ${removedToolFile}`));
           }
         }
 
@@ -711,7 +714,7 @@ export async function runProjectConfiguration(options) {
         }
 
         // Remove from integrationBlockHashes (keyed by tool file path)
-        const toolFileName = getToolFilePath(tool);
+        const toolFileName = removedToolFile;
         if (manifest.integrationBlockHashes?.[toolFileName]) {
           delete manifest.integrationBlockHashes[toolFileName];
         }
@@ -934,7 +937,8 @@ export async function runProjectConfiguration(options) {
     const generatedFiles = new Set();
 
     for (const tool of newAITools) {
-      const targetFile = getToolFilePath(tool);
+      // XSPEC-418 R3
+      const targetFile = resolveIntegrationTargetFile(tool, manifest);
       if (generatedFiles.has(targetFile)) {
         continue; // Skip if already generated (AGENTS.md sharing)
       }
@@ -947,7 +951,9 @@ export async function runProjectConfiguration(options) {
         standardsFormat: manifest.format || 'ai',
         contentMode: newContentMode,
         // Pass output_language for dynamic commit standards generation
-        outputLanguage: newOptions.output_language || 'english'
+        outputLanguage: newOptions.output_language || 'english',
+        // XSPEC-418 R2/R3
+        integrationTargets: manifest.integrationTargets
       };
 
       const result = writeIntegrationFile(tool, toolConfig, projectPath);
@@ -1052,7 +1058,7 @@ export async function runProjectConfiguration(options) {
   manifest.options = newOptions;
   manifest.contentMode = newContentMode;
   manifest.aiTools = newAITools;
-  manifest.version = '3.2.0';
+  bumpManifestVersion(manifest);
 
   // Update methodology
   if (newMethodology) {

package/src/commands/init.js

@@ -26,7 +26,7 @@ import { displayLanguageToLocale } from '../utils/locale.js';
 import { generateReleaseConfig, RELEASE_MODE_LABELS } from '../utils/release-config.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
 import { readInstallYaml } from '../utils/config-manager.js';
-import { getToolFilePath } from '../utils/integration-generator.js';
+import { resolveIntegrationTargetFile } from '../utils/integration-generator.js';
 import { withFileTransaction } from '../utils/transaction.js';
 
 /**
@@ -107,7 +107,10 @@ export async function initCommand(options) {
   // `uds init` re-installs them idempotently.
   const ownedPaths = [join(projectPath, '.standards')];
   for (const tool of (config.integrations || config.aiTools || [])) {
-    const file = getToolFilePath(tool);
+    // XSPEC-418 R2: honors --claude-target so a local-target install's owned
+    // path is CLAUDE.local.md, not CLAUDE.md — rollback must tear down the
+    // file actually written, not the tool's default.
+    const file = resolveIntegrationTargetFile(tool, { integrationTargets: config.integrationTargets });
     if (file) ownedPaths.push(join(projectPath, file));
   }
   if (config.generateAgentsMd) ownedPaths.push(join(projectPath, 'AGENTS.md'));
@@ -658,6 +661,23 @@ function buildNonInteractiveConfig(options, detected, projectPath) {
     ? false // codex/opencode handles AGENTS.md, skip universal output
     : (options.agentsMd !== undefined ? !!options.agentsMd : true);
 
+  // XSPEC-418 R2: --claude-target <project|local>, default 'project'. An
+  // unrecognized value is never substituted quietly (same policy as
+  // --content-mode above) — it falls back to 'project' with a warning rather
+  // than silently writing into CLAUDE.local.md or vice versa.
+  let claudeTargetFlag = options.claudeTarget || 'project';
+  if (claudeTargetFlag !== 'project' && claudeTargetFlag !== 'local') {
+    console.log(chalk.yellow(
+      `⚠ Unknown --claude-target '${claudeTargetFlag}'; using 'project'. Supported: project, local.`
+    ));
+    claudeTargetFlag = 'project';
+  }
+  // Only ever set when 'local' — 'project' or unspecified leaves the manifest
+  // shape completely unchanged (XSPEC-418 AC-5).
+  const integrationTargets = claudeTargetFlag === 'local'
+    ? { 'claude-code': 'CLAUDE.local.md' }
+    : undefined;
+
   return {
     languages: options.lang ? [options.lang] : Object.keys(detected.languages).filter(k => detected.languages[k]),
     frameworks: options.framework ? [options.framework] : Object.keys(detected.frameworks).filter(k => detected.frameworks[k]),
@@ -678,7 +698,8 @@ function buildNonInteractiveConfig(options, detected, projectPath) {
     generateAgentsMd,
     releaseMode: options.releaseMode || 'ci-cd',
     withHooks: !!options.withHooks,
-    contentLayout: options.contentLayout || 'flat'
+    contentLayout: options.contentLayout || 'flat',
+    integrationTargets
   };
 }