universal-dev-standards 6.9.0 → 6.11.0

package/src/commands/update.js

@@ -1,15 +1,16 @@
 import chalk from 'chalk';
-import ora from 'ora';
+import { createSpinner } from '../utils/spinner.js';
 import { select, confirm as inquirerConfirm, checkbox, Separator } from '@inquirer/prompts';
 import { execSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
 import { join, basename, dirname, relative } from 'path';
 import { readManifest, writeManifest, copyStandard, isInitialized, getRepoRoot } from '../utils/copier.js';
-import { getRepositoryInfo, getAllStandards, getStandardSource } from '../utils/registry.js';
-import { computeFileHash, planStandardsRemovals, refreshIntegrationBlockHashes } from '../utils/hasher.js';
+import { getRepositoryInfo, getAllStandards, getShippableFilenames, getStandardSource } from '../utils/registry.js';
+import { computeFileHash, planStandardsRemovals, refreshIntegrationBlockHashes, pruneIntegrationFileHashes } from '../utils/hasher.js';
+import { AmbiguousMarkerError } from '../utils/marker-locator.js';
 import {
   writeIntegrationFile,
-  getToolFilePath,
+  resolveIntegrationTargetFile,
   writeAgentsMdSummary,
   resolveContentModeForTool,
   generateIntegrationContent,
@@ -18,6 +19,7 @@ import {
 } from '../utils/integration-generator.js';
 import {
   calculateCategoriesFromStandards,
+  repairIntegrationConfigCategories,
   arraysEqual,
   getToolFromPath
 } from '../utils/reference-sync.js';
@@ -56,13 +58,14 @@ 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 { resolveIntegrationFile, SUPPORTED_AI_TOOLS, getToolFormat } from '../core/constants.js';
 import {
   mergeInstalledNames,
   recordFileProvenance,
   forgetFileProvenance,
   establishProvenance,
-  isProvenanceEstablished
+  isProvenanceEstablished,
+  bumpManifestVersion
 } from '../core/manifest.js';
 
 /**
@@ -274,7 +277,7 @@ function buildInstallCommand(pm, tag) {
  */
 async function updateCliAndExit(useBeta = false) {
   const msg = t().commands.update;
-  const spinner = ora(msg.updatingCli).start();
+  const spinner = createSpinner(msg.updatingCli).start();
 
   try {
     // Command is hardcoded - no user input, safe from injection
@@ -438,6 +441,15 @@ export async function updateCommand(options) {
   console.log(chalk.bold(msg.title));
   console.log(chalk.gray('─'.repeat(50)));
 
+  // Handle --claude-target option (XSPEC-418 R4): switch an EXISTING
+  // installation's claude-code integration target between CLAUDE.md and
+  // CLAUDE.local.md, without a full reinstall. Standalone, like --sync-refs
+  // below — it does not compose with other update modes/scopes.
+  if (options.claudeTarget) {
+    await switchClaudeTarget(projectPath, manifest, options.claudeTarget, options);
+    return;
+  }
+
   // Handle --sync-refs option.
   // `--plan` is honoured here too. This branch is above the mode dispatch
   // because sync-refs is its own operation rather than a scope of the
@@ -489,7 +501,7 @@ export async function updateCommand(options) {
   // Handle --plan option (DSR dry-run). Nothing below this line writes.
   if (options.plan) {
     if (!scopedToSkills && !scopedToCommands) {
-      await handlePlan(projectPath, options);
+      await handlePlan(projectPath, options, manifest);
     }
     if (scopedToSkills) await planSkills(projectPath, manifest, options);
     if (scopedToCommands) await planCommands(projectPath, manifest, options);
@@ -581,6 +593,23 @@ export async function updateCommand(options) {
     if (versionComparison > 0) {
       console.log(chalk.gray(`  ${msg.newerVersion.replace('{version}', currentVersion)}`));
     }
+
+    // Still forget records of files that are gone and no longer shipped. An
+    // adopter who followed MIGRATION-v6 §2 is on the current version by
+    // definition — telling them to run `uds update --prune` and then returning
+    // before anything is examined is how the complaint became unclearable.
+    const retiredOnLatest = pruneRetiredHashes(manifest, projectPath);
+    if (retiredOnLatest.length > 0) {
+      console.log();
+      console.log(chalk.gray(
+        `  ${(msg.droppedRetiredHashes || 'Dropped {count} manifest record(s) for files UDS no longer ships and that are already gone:').replace('{count}', retiredOnLatest.length)}`
+      ));
+      for (const path of retiredOnLatest) {
+        console.log(chalk.gray(`    - ${path}`));
+      }
+      writeManifest(manifest, projectPath);
+    }
+
     console.log();
     return;
   }
@@ -642,7 +671,7 @@ export async function updateCommand(options) {
 
   // Perform update
   console.log();
-  const spinner = ora(msg.updatingStandards).start();
+  const spinner = createSpinner(msg.updatingStandards).start();
 
   const results = {
     updated: [],
@@ -714,7 +743,7 @@ export async function updateCommand(options) {
     }
 
     if (shouldInstallNew) {
-      const newSpinner = ora(msg.installingNewStandards).start();
+      const newSpinner = createSpinner(msg.installingNewStandards).start();
       let newCount = 0;
 
       for (const ns of newStandards) {
@@ -735,7 +764,17 @@ export async function updateCommand(options) {
 
   // Update integrations (unless --standards-only)
   if (!options.standardsOnly && manifest.integrations && manifest.integrations.length > 0) {
-    const intSpinner = ora(msg.syncingIntegrations).start();
+    // XSPEC adopter-report Q1 follow-up: this block writes
+    // integrationBlockHashes but never touched manifest.integrationConfigs at
+    // all, so a manifest that picked up a broken (empty/unrecognized)
+    // categories array from an older buggy `--sync-refs` run stayed broken
+    // through every subsequent plain `uds update` — the only path that
+    // repaired it was `--sync-refs` itself. Self-heal corruption here too, not
+    // just there; an already-valid list is left alone (see
+    // repairIntegrationConfigCategories's docblock for why).
+    repairIntegrationConfigCategories(manifest);
+
+    const intSpinner = createSpinner(msg.syncingIntegrations).start();
 
     // Build installed standards list
     // Raw, not basename()d. Resolution needs the registry (an ID is not a
@@ -756,7 +795,9 @@ export async function updateCommand(options) {
     const aiTools = manifest.aiTools || [];
 
     for (const tool of aiTools) {
-      const targetFile = getToolFilePath(tool);
+      // XSPEC-418 R3: honors manifest.integrationTargets — the tool's file may
+      // be CLAUDE.local.md, not the hardcoded default.
+      const targetFile = resolveIntegrationTargetFile(tool, manifest);
       if (generatedFiles.has(targetFile)) {
         continue; // Skip if already generated (AGENTS.md sharing)
       }
@@ -773,7 +814,9 @@ export async function updateCommand(options) {
         contentMode: resolved.contentMode,
         level: resolved.level,
         // Pass output_language for dynamic commit standards generation
-        outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english'
+        outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || 'english',
+        // XSPEC-418 R2/R3: so writeIntegrationFile resolves the actual target.
+        integrationTargets: manifest.integrationTargets
       };
 
       const result = writeIntegrationFile(tool, toolConfig, projectPath);
@@ -813,6 +856,7 @@ export async function updateCommand(options) {
             installedAt: new Date().toISOString()
           };
         }
+        refreshTrackedFileHash(manifest, projectPath, agentsMdResult.path);
       }
     }
 
@@ -831,7 +875,11 @@ export async function updateCommand(options) {
     if (manifest.integrationBlockHashes) {
       const expectedFiles = new Set();
       for (const tool of (manifest.aiTools || [])) {
-        const targetFile = getToolFilePath(tool);
+        // XSPEC-418 R3: an expected set built from the hardcoded default file
+        // pruned CLAUDE.local.md's own hash the moment a local-target install
+        // ran this cleanup — it looked orphaned because nothing here knew the
+        // real target had moved.
+        const targetFile = resolveIntegrationTargetFile(tool, manifest);
         if (targetFile) expectedFiles.add(targetFile);
       }
       // Universal AGENTS.md is tracked when generateAgentsMd is enabled.
@@ -862,8 +910,14 @@ export async function updateCommand(options) {
       if (!layeredResult.fallback) {
         console.log(chalk.green(`  ✓ Layered CLAUDE.md updated (${layeredResult.generatedFiles.length} files)`));
       }
-    } catch {
-      // Silently skip if generator not available
+    } catch (error) {
+      // XSPEC adopter-report Q5: an ambiguous marker pair is a real problem
+      // the adopter needs to see — refuse that one write and say why,
+      // rather than folding it into "generator not available".
+      if (error instanceof AmbiguousMarkerError) {
+        console.log(chalk.red(`  ✗ Layered CLAUDE.md not updated: ${error.message}`));
+      }
+      // Otherwise: silently skip if generator not available
     }
   }
 
@@ -933,14 +987,14 @@ export async function updateCommand(options) {
     }
   }
 
-  // Update hashes for integrations
-  for (const int of results.integrations) {
-    const fullPath = join(projectPath, int);
-    const hashInfo = computeFileHash(fullPath);
-    if (hashInfo) {
-      manifest.fileHashes[int] = { ...hashInfo, installedAt: now };
-    }
-  }
+  // XSPEC-418 R6: integration files (results.integrations — CLAUDE.md,
+  // CLAUDE.local.md, AGENTS.md, etc.) are tracked by their UDS block in
+  // integrationBlockHashes, not by whole-file hash here. A whole-file entry
+  // for one of these disagrees the moment the adopter edits anything outside
+  // the block — exactly the customization the marker-based update preserves —
+  // and made `uds check` report "modified" while its own block-integrity
+  // check said the block was intact. See pruneIntegrationFileHashes below for
+  // cleanup of any such entry an older CLI already wrote.
 
   // Record what UDS wrote this run, then decide what (if anything) may go.
   // (XSPEC-384 R1/R2/R3)
@@ -989,6 +1043,22 @@ export async function updateCommand(options) {
     }
   }
 
+  // Records of files that are already gone and that UDS no longer ships. Not
+  // part of the removal plan above: that plan walks what is on disk, and these
+  // are precisely the ones that are not. Reported rather than done quietly,
+  // because a manifest shrinking without explanation is the shape this whole
+  // release is about.
+  const retiredHashes = pruneRetiredHashes(manifest, projectPath);
+  if (retiredHashes.length > 0) {
+    console.log();
+    console.log(chalk.gray(
+      `  ${(msg.droppedRetiredHashes || 'Dropped {count} manifest record(s) for files UDS no longer ships and that are already gone:').replace('{count}', retiredHashes.length)}`
+    ));
+    for (const path of retiredHashes) {
+      console.log(chalk.gray(`    - ${path}`));
+    }
+  }
+
   // Provenance is only a complete account of what we own once a run has
   // written the whole installed set. Until then every unrecorded file is
   // `unknown` rather than `foreign`, and nothing gets deleted on the strength
@@ -1052,7 +1122,7 @@ export async function updateCommand(options) {
   // date. The manifest is still written so that hash/migration bookkeeping for
   // the files that DID succeed is persisted.
   const updateIncomplete = results.errors.length > 0;
-  manifest.version = '3.3.0';
+  bumpManifestVersion(manifest);
   if (!updateIncomplete) {
     manifest.upstream.version = latestVersion;
     manifest.upstream.installed = new Date().toISOString().split('T')[0];
@@ -1085,8 +1155,9 @@ export async function updateCommand(options) {
     allTrackedFiles.push(join('.standards', fileName));
   }
   for (const intEntry of (manifest.integrations || [])) {
-    // 兩種形狀都要能解出路徑（XSPEC-343 R1）
-    const filePath = resolveIntegrationFile(intEntry) || getToolFilePath(intEntry);
+    // 兩種形狀都要能解出路徑（XSPEC-343 R1），且要尊重 manifest.integrationTargets
+    // 的目標覆寫（XSPEC-418 R2/R3）——resolveIntegrationTargetFile 已同時處理兩者。
+    const filePath = resolveIntegrationTargetFile(intEntry, manifest);
     if (filePath) {
       allTrackedFiles.push(filePath);
     }
@@ -1110,7 +1181,7 @@ export async function updateCommand(options) {
     }
 
     if (shouldRestore) {
-      const restoreSpinner = ora((msg.restoringMissing || 'Restoring missing files...')).start();
+      const restoreSpinner = createSpinner((msg.restoringMissing || 'Restoring missing files...')).start();
       const checkMsg = t().commands.check;
       let restoredCount = 0;
 
@@ -1177,7 +1248,7 @@ export async function updateCommand(options) {
 
         // Install Skills if user agreed
         if (installSkills.length > 0) {
-          const skillSpinner = ora(msg.installingNewSkills || 'Installing Skills...').start();
+          const skillSpinner = createSpinner(msg.installingNewSkills || 'Installing Skills...').start();
           const skillsLocale = resolveLocale(manifest, projectPath, options);
           const skillResult = await installSkillsToMultipleAgents(installSkills, null, projectPath, skillsLocale);
 
@@ -1225,7 +1296,7 @@ export async function updateCommand(options) {
 
         // Update outdated Skills if user agreed
         if (updateSkills.length > 0) {
-          const updateSpinner = ora(msg.updatingSkills || 'Updating Skills...').start();
+          const updateSpinner = createSpinner(msg.updatingSkills || 'Updating Skills...').start();
           const updateLocale = resolveLocale(manifest, projectPath, options);
           const updateResult = await installSkillsToMultipleAgents(updateSkills, null, projectPath, updateLocale);
 
@@ -1263,7 +1334,7 @@ export async function updateCommand(options) {
 
         // Install Commands if user agreed
         if (installCommands.length > 0) {
-          const cmdSpinner = ora(msg.installingNewCommands || 'Installing commands...').start();
+          const cmdSpinner = createSpinner(msg.installingNewCommands || 'Installing commands...').start();
           const cmdLocale = resolveLocale(manifest, projectPath, options);
           const cmdResult = await installCommandsToMultipleAgents(installCommands, null, projectPath, cmdLocale);
 
@@ -1294,7 +1365,7 @@ export async function updateCommand(options) {
 
         // Update outdated Commands if user agreed
         if (updateCommands.length > 0) {
-          const updateCmdSpinner = ora(msg.updatingCommands || 'Updating Commands...').start();
+          const updateCmdSpinner = createSpinner(msg.updatingCommands || 'Updating Commands...').start();
           const updateCmdLocale = resolveLocale(manifest, projectPath, options);
           const updateCmdResult = await installCommandsToMultipleAgents(updateCommands, null, projectPath, updateCmdLocale);
 
@@ -1370,7 +1441,7 @@ export async function updateCommand(options) {
         let hasChanges = false;
 
         if (missingSkills.length > 0) {
-          const spinner = ora(msg.installingNewSkills || 'Installing Skills...').start();
+          const spinner = createSpinner(msg.installingNewSkills || 'Installing Skills...').start();
           const result = await installSkillsToMultipleAgents(missingSkills, null, projectPath, skillsLocale);
           if (!manifest.skills) manifest.skills = {};
           manifest.skills.installed = true;
@@ -1391,7 +1462,7 @@ export async function updateCommand(options) {
         }
 
         if (outdatedSkills.length > 0) {
-          const spinner = ora(msg.updatingSkills || 'Updating Skills...').start();
+          const spinner = createSpinner(msg.updatingSkills || 'Updating Skills...').start();
           const result = await installSkillsToMultipleAgents(outdatedSkills, null, projectPath, skillsLocale);
           if (!manifest.skills) manifest.skills = {};
           manifest.skills.version = repoInfo.skills.version;
@@ -1415,7 +1486,7 @@ export async function updateCommand(options) {
         }
 
         if (missingCommands.length > 0) {
-          const spinner = ora(msg.installingNewCommands || 'Installing commands...').start();
+          const spinner = createSpinner(msg.installingNewCommands || 'Installing commands...').start();
           const result = await installCommandsToMultipleAgents(missingCommands, null, projectPath, skillsLocale);
           if (!manifest.commands) manifest.commands = {};
           manifest.commands.installed = true;
@@ -1435,7 +1506,7 @@ export async function updateCommand(options) {
         }
 
         if (outdatedCommands.length > 0) {
-          const spinner = ora(msg.updatingCommands || 'Updating Commands...').start();
+          const spinner = createSpinner(msg.updatingCommands || 'Updating Commands...').start();
           const result = await installCommandsToMultipleAgents(outdatedCommands, null, projectPath, skillsLocale);
           if (!manifest.commands) manifest.commands = {};
           manifest.commands.version = repoInfo.skills.version;
@@ -1607,6 +1678,140 @@ async function offerErrorExitGate(projectPath, options) {
   console.log();
 }
 
+/**
+ * Switch the claude-code integration's target file between CLAUDE.md and
+ * CLAUDE.local.md for an EXISTING installation, without a full reinstall.
+ * // implements XSPEC-418 R4
+ *
+ * The scenario this exists for: an adopter installed with the default target
+ * (CLAUDE.md), then either hand-moved the UDS block to CLAUDE.local.md (it now
+ * exists there with markers already) or wants to move it there for the first
+ * time. Either way `uds update --claude-target local` should leave exactly one
+ * up-to-date block in the new target and none in the old one.
+ *
+ * @param {string} projectPath
+ * @param {Object} manifest - Mutated and written to disk on success
+ * @param {string} target - 'project' | 'local'
+ * @param {Object} options - CLI options (unused today; kept for symmetry with
+ *   the other option handlers and so a future confirmation prompt has somewhere
+ *   to read --yes from)
+ */
+async function switchClaudeTarget(projectPath, manifest, target, options) { // eslint-disable-line no-unused-vars
+  if (target !== 'project' && target !== 'local') {
+    console.log(chalk.red(`  ✗ --claude-target must be "project" or "local", got "${target}"`));
+    console.log();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!(manifest.aiTools || []).includes('claude-code')) {
+    console.log(chalk.yellow('  claude-code is not among the configured AI tools — nothing to switch.'));
+    console.log();
+    return;
+  }
+
+  const oldFile = resolveIntegrationTargetFile('claude-code', manifest);
+  const newFile = target === 'local' ? 'CLAUDE.local.md' : 'CLAUDE.md';
+
+  if (oldFile === newFile) {
+    console.log(chalk.gray(`  claude-code integration already targets ${newFile}. Nothing to do.`));
+    console.log();
+    return;
+  }
+
+  console.log(chalk.cyan(`  Switching claude-code integration target: ${oldFile} → ${newFile}`));
+
+  // 1. Remove the UDS block from the OLD file, preserving any user content —
+  // the same rule uninstallIntegrations already applies. A file left 100%
+  // UDS-generated once the block is gone is deleted outright.
+  const oldPath = join(projectPath, oldFile);
+  if (existsSync(oldPath)) {
+    const format = getToolFormat('claude-code');
+    const content = readFileSync(oldPath, 'utf-8');
+    // XSPEC adopter-report Q5: an ambiguous marker pair means this write
+    // must refuse rather than guess which block to move — report and leave
+    // the old file untouched instead of switching targets on a bad guess.
+    let parts;
+    try {
+      parts = extractMarkedContent(content, format);
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        console.log(chalk.red(`    ✗ ${oldFile}: ${error.message}`));
+        console.log(chalk.gray(`      Not switching — fix the marker pair in ${oldFile} first.`));
+        process.exitCode = 1;
+        return;
+      }
+      throw error;
+    }
+    if (parts.content) {
+      const userContent = (parts.before.trim() + parts.after.trim()).trim();
+      if (userContent.length > 0) {
+        const cleaned = (parts.before + parts.after).trim() + '\n';
+        writeFileSync(oldPath, cleaned, 'utf-8');
+        console.log(chalk.gray(`    ${oldFile}: UDS block removed, your content kept`));
+      } else {
+        unlinkSync(oldPath);
+        console.log(chalk.gray(`    ${oldFile}: deleted (was 100% UDS-generated)`));
+      }
+    }
+    // else: no UDS markers found in the old file (already moved by hand) —
+    // nothing UDS-owned to remove.
+  }
+  if (manifest.integrationBlockHashes) delete manifest.integrationBlockHashes[oldFile];
+  if (manifest.fileHashes) delete manifest.fileHashes[oldFile];
+
+  // 2. Point the manifest at the new target. Switching back to 'project'
+  // removes the override entirely rather than writing it as 'CLAUDE.md', so a
+  // round-tripped manifest is shaped exactly as if local had never been chosen
+  // (XSPEC-418 AC-5).
+  if (target === 'local') {
+    manifest.integrationTargets = { ...(manifest.integrationTargets || {}), 'claude-code': 'CLAUDE.local.md' };
+  } else if (manifest.integrationTargets) {
+    delete manifest.integrationTargets['claude-code'];
+    if (Object.keys(manifest.integrationTargets).length === 0) delete manifest.integrationTargets;
+  }
+
+  // 3. Write (or update in place) the new target. writeIntegrationFile already
+  // does a marker-based UPDATE when the file exists and has UDS markers — the
+  // "hand-moved to CLAUDE.local.md already" arm of R4 — and only appends when
+  // it does not, so this one call covers both AC-4 arms.
+  const toolConfig = buildToolIntegrationConfig(manifest, 'claude-code');
+  const result = writeIntegrationFile('claude-code', toolConfig, projectPath);
+  if (!result.success) {
+    console.log(chalk.red(`  ✗ Failed to write ${newFile}: ${result.error}`));
+    console.log();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.blockHashInfo) {
+    if (!manifest.integrationBlockHashes) manifest.integrationBlockHashes = {};
+    manifest.integrationBlockHashes[result.path] = {
+      ...result.blockHashInfo,
+      installedAt: new Date().toISOString()
+    };
+  }
+  // XSPEC-418 R6: no whole-file fileHashes entry for the new target either —
+  // only its UDS block is tracked, above.
+
+  // 4. manifest.integrations may record the old file path (XSPEC-343 shapes) —
+  // point it at the new one instead of leaving a stale entry check would then
+  // report as missing.
+  manifest.integrations = (manifest.integrations || []).map(entry => (entry === oldFile ? newFile : entry));
+  if (!manifest.integrations.includes(newFile) && !manifest.integrations.includes('claude-code')) {
+    manifest.integrations.push(newFile);
+  }
+
+  // XSPEC-418 R6: also catches a stale whole-file entry for either file left
+  // by an older CLI, not just the one this run might otherwise have added.
+  pruneIntegrationFileHashes(manifest);
+
+  writeManifest(manifest, projectPath);
+
+  console.log(chalk.green(`  ✓ claude-code now targets ${newFile}`));
+  console.log();
+}
+
 /**
  * Regenerate integration files for all configured AI tools
  * Reusable core logic that can be called from both updateIntegrationsOnly and configureCommand
@@ -1631,12 +1836,15 @@ export function regenerateIntegrations(projectPath, manifest) {
   const now = new Date().toISOString();
 
   for (const tool of aiTools) {
-    const targetFile = getToolFilePath(tool);
+    // XSPEC-418 R3
+    const targetFile = resolveIntegrationTargetFile(tool, manifest);
     if (generatedFiles.has(targetFile)) {
       continue; // Skip if already generated (AGENTS.md sharing)
     }
 
     // Shared with the reconciler so both paths emit the identical block.
+    // buildToolIntegrationConfig already carries manifest.integrationTargets
+    // through to writeIntegrationFile (XSPEC-418 R2).
     const toolConfig = buildToolIntegrationConfig(manifest, tool);
 
     const result = writeIntegrationFile(tool, toolConfig, projectPath);
@@ -1644,16 +1852,11 @@ export function regenerateIntegrations(projectPath, manifest) {
       results.updated.push(result.path);
       generatedFiles.add(targetFile);
 
-      // Update file hash
-      const fullPath = join(projectPath, result.path);
-      const hashInfo = computeFileHash(fullPath);
-      if (hashInfo) {
-        if (!manifest.fileHashes) {
-          manifest.fileHashes = {};
-        }
-        const normalizedPath = result.path.replace(/\\/g, '/');
-        manifest.fileHashes[normalizedPath] = { ...hashInfo, installedAt: now };
-      }
+      // XSPEC-418 R6: no whole-file `fileHashes` entry for an integration
+      // file — only the UDS block is tracked, below. A whole-file entry here
+      // is exactly what made `uds check` report "CLAUDE.md (modified)" for
+      // content outside the block that UDS's own marker-based update leaves
+      // alone on purpose.
 
       // Track integration block hash for UDS content integrity
       if (result.blockHashInfo) {
@@ -1688,9 +1891,18 @@ export function regenerateIntegrations(projectPath, manifest) {
           installedAt: now
         };
       }
+      refreshTrackedFileHash(manifest, projectPath, agentsMdResult.path);
     }
   }
 
+  // XSPEC-418 R6: drop any fileHashes entry left over from an older CLI (or
+  // from refreshTrackedFileHash above, which predates this rule and still
+  // refreshes AGENTS.md's whole-file hash if one is already tracked). Called
+  // here rather than relying only on refreshIntegrationBlockHashes downstream
+  // because not every caller of this function calls that afterward (`uds
+  // config`'s AI-tools flow does not).
+  pruneIntegrationFileHashes(manifest);
+
   return {
     success: results.errors.length === 0,
     updated: results.updated,
@@ -1758,9 +1970,11 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
     console.log(chalk.bold('=== Integration Plan (dry run — nothing is written) ==='));
     const wouldChange = [];
     const unchanged = [];
+    const ambiguous = [];
     const seen = new Set();
     for (const tool of aiTools) {
-      const targetFile = getToolFilePath(tool);
+      // XSPEC-418 R3: the plan must show the actual target, not the default.
+      const targetFile = resolveIntegrationTargetFile(tool, manifest);
       if (seen.has(targetFile)) continue;
       seen.add(targetFile);
       const savedMode = manifest.contentMode || 'auto';
@@ -1787,7 +2001,18 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
       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 || '';
+      // XSPEC adopter-report Q5: an ambiguous marker pair can't be diffed
+      // against — report it explicitly instead of crashing the whole plan.
+      let cur;
+      try {
+        cur = extractMarkedContent(current, format).content || '';
+      } catch (error) {
+        if (error instanceof AmbiguousMarkerError) {
+          ambiguous.push(`${targetFile}: ${error.message}`);
+          continue;
+        }
+        throw error;
+      }
       // 比對正規化過的內容：只關心「受管區塊會不會變」，不關心尾端空白。
       if (cur.trim() === String(next).trim()) {
         unchanged.push(targetFile);
@@ -1796,6 +2021,10 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
         wouldChange.push(`${targetFile} (${delta >= 0 ? '+' : ''}${delta} bytes in the UDS block)`);
       }
     }
+    if (ambiguous.length > 0) {
+      console.log(chalk.red(`  ✗ Ambiguous UDS markers (${ambiguous.length}) — will not be touched by --apply:`));
+      for (const a of ambiguous) console.log(chalk.gray(`      ${a}`));
+    }
     if (wouldChange.length > 0) {
       console.log(chalk.yellow(`  ~ Would update (${wouldChange.length}):`));
       for (const f of wouldChange) console.log(chalk.gray(`      ${f}`));
@@ -1811,7 +2040,7 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
     return;
   }
 
-  const spinner = ora(msg.regeneratingIntegrations).start();
+  const spinner = createSpinner(msg.regeneratingIntegrations).start();
 
   // Use reusable regeneration function
   const results = regenerateIntegrations(projectPath, manifest);
@@ -1819,7 +2048,7 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
   spinner.succeed(msg.regeneratedIntegrations.replace('{count}', results.updated.length));
 
   // Update manifest
-  manifest.version = '3.3.0';
+  bumpManifestVersion(manifest);
   refreshIntegrationBlockHashes(manifest, projectPath);
   writeManifest(manifest, projectPath);
 
@@ -1840,6 +2069,199 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
   process.exit(0);
 }
 
+/**
+ * Rebuild `manifest.integrationConfigs` from what the manifest already records.
+ *
+ * 🔴 Only `uds init`'s interactive flow and `--sync-refs` itself ever wrote this
+ * key; no update or reconcile path backfills it, so a project created with
+ * `uds init -y` carries `{}` from the first day (reproduced on a clean 6.9.0
+ * project, 2026-09-16). `--sync-refs` then refuses to run — and `uds check` was
+ * recommending exactly that command. Everything the config holds is derivable
+ * from the manifest, so derive it instead of demanding the user re-init.
+ *
+ * Existing entries are never overwritten: they may hold choices (categories,
+ * content mode) that this derivation cannot know.
+ *
+ * @param {Object} manifest - Manifest object (mutated)
+ * @returns {number} How many entries were added
+ */
+export function backfillIntegrationConfigs(manifest) {
+  if (!manifest.integrationConfigs) manifest.integrationConfigs = {};
+
+  const tools = manifest.aiTools?.length ? manifest.aiTools : [];
+  const byFile = new Map();
+  for (const tool of tools) {
+    // XSPEC-418 R3: keyed by the actual target file, or integrationConfigs
+    // would key claude-code's entry as 'CLAUDE.md' while every other record
+    // (integrations, integrationBlockHashes) already uses CLAUDE.local.md.
+    const file = resolveIntegrationTargetFile(tool, manifest);
+    if (file && !byFile.has(file)) byFile.set(file, tool);
+  }
+  // Integrations can be recorded as file names (`CLAUDE.md`) or tool keys.
+  for (const entry of manifest.integrations || []) {
+    const file = resolveIntegrationFile(entry) || (String(entry).includes('.') ? String(entry) : null);
+    if (!file) continue;
+    if (!byFile.has(file)) {
+      const tool = getToolFromPath(file) || resolveToolKeyFromEntry(entry);
+      if (tool) byFile.set(file, tool);
+    }
+  }
+
+  let added = 0;
+  for (const [file, tool] of byFile) {
+    if (manifest.integrationConfigs[file]) continue;
+    manifest.integrationConfigs[file] = {
+      ...buildToolIntegrationConfig(manifest, tool),
+      format: manifest.format || 'ai',
+      backfilledAt: new Date().toISOString()
+    };
+    added++;
+  }
+  return added;
+}
+
+function resolveToolKeyFromEntry(entry) {
+  const key = String(entry).replace(/\.[^.]+$/, '').toLowerCase();
+  return SUPPORTED_AI_TOOLS?.[key] ? key : null;
+}
+
+/**
+ * If the manifest already tracks this file, make its record describe what is on
+ * disk now.
+ *
+ * Every path that writes AGENTS.md recorded `integrationBlockHashes` and none
+ * recorded `fileHashes`, so a project whose manifest tracked the file (an older
+ * install, or one where AGENTS.md was written as a tool's integration file) got
+ * `⚠ AGENTS.md (modified)` from `uds check` the moment UDS itself regenerated
+ * it. UDS wrote the file and did not record what it wrote.
+ *
+ * Conditional on purpose. `uds init` does not enrol AGENTS.md in `fileHashes`,
+ * and adopters are expected to extend that summary — a path that started
+ * tracking it would convert every legitimate edit into a reported fault. This
+ * only ever refreshes a record that already exists.
+ *
+ * XSPEC-418 R6 narrowed that further: AGENTS.md is also tracked by its UDS
+ * block (`integrationBlockHashes`) once one exists, and every call site of
+ * this function now also calls `pruneIntegrationFileHashes` afterward — so a
+ * `fileHashes` entry this refreshes is removed again in the same run. Kept
+ * (rather than deleted outright) because it still matters for the moment
+ * between this call and the prune, and for any caller added later that
+ * forgets to prune; the prune is what actually enforces R6.
+ *
+ * @param {Object} manifest - Project manifest (mutated)
+ * @param {string} projectPath - Project root
+ * @param {string} relativePath - Path as UDS reports it
+ * @returns {boolean} Whether a record was refreshed
+ */
+export function refreshTrackedFileHash(manifest, projectPath, relativePath) {
+  if (!manifest?.fileHashes || !relativePath) return false;
+  const normalized = String(relativePath).replace(/\\/g, '/');
+  if (!(normalized in manifest.fileHashes)) return false;
+
+  const hashInfo = computeFileHash(join(projectPath, normalized));
+  if (!hashInfo) return false;
+
+  manifest.fileHashes[normalized] = { ...hashInfo, installedAt: new Date().toISOString() };
+  return true;
+}
+
+/**
+ * Forget `fileHashes` records for files that are gone AND that UDS no longer
+ * ships.
+ *
+ * `--prune` deletes files it finds while walking `.standards/`. A file the
+ * adopter already removed by hand is not in that walk, so its record survived
+ * every prune — and the record is what made `uds check` report the completed
+ * migration as seven faults. Following MIGRATION-v6 §2 therefore produced a
+ * complaint that no command could clear.
+ *
+ * This is not a deletion. The file is already absent and no registry entry can
+ * ever resolve to it again, so the record cannot refer to anything. Both facts
+ * are required: a missing file UDS still ships is a real fault and stays; a
+ * descoped standard still on disk is `--prune`'s business, gated on ownership,
+ * and is left alone here.
+ *
+ * @param {Object} manifest - Project manifest (mutated)
+ * @param {string} projectPath - Project root
+ * @param {{shippable?: Set<string>}} [deps] - Injection point for tests
+ * @returns {string[]} Paths whose records were dropped, sorted
+ */
+export function pruneRetiredHashes(manifest, projectPath, deps = {}) {
+  if (!manifest?.fileHashes) return [];
+
+  let shippable;
+  try {
+    shippable = deps.shippable || getShippableFilenames();
+  } catch {
+    return [];
+  }
+
+  // A shippable set this small means the registry did not load, not that UDS
+  // stopped shipping everything. Without this arm a broken install would empty
+  // the manifest and every downstream check would go quiet at the same time.
+  if (!shippable || shippable.size < 50) return [];
+
+  const dropped = [];
+  for (const recorded of Object.keys(manifest.fileHashes)) {
+    const normalized = recorded.replace(/\\/g, '/');
+    if (!normalized.startsWith('.standards/')) continue;
+    const fileName = normalized.split('/').pop();
+    if (shippable.has(fileName)) continue;
+    if (existsSync(join(projectPath, recorded))) continue;
+    delete manifest.fileHashes[recorded];
+    dropped.push(recorded);
+  }
+  return dropped.sort();
+}
+
+/**
+ * Build the config `--sync-refs` regenerates an integration file from.
+ *
+ * The stored `integrationConfigs[file]` is a snapshot taken when the file was
+ * installed. Its `categories` are the thing sync-refs exists to update, and its
+ * `installedStandards` is the thing that must never be trusted: it is not
+ * refreshed by any path, so on a project upgraded across majors it still lists
+ * standards that stopped shipping, and whatever it lists becomes the file's
+ * content. That is how a manifest holding 73 standards produced a CLAUDE.md
+ * announcing 76, which `uds check` then flagged against the same manifest.
+ *
+ * So: manifest-derived fields win, the caller's freshly computed categories win
+ * over both, and anything the manifest knows nothing about (timestamps, fields
+ * a future version adds) is carried through untouched.
+ *
+ * `outputLanguage` is the one place the stored value still gets a say — a
+ * manifest with no `output_language` should not silently reset a project that
+ * chose one before the option was recorded there.
+ *
+ * @param {Object} manifest - Project manifest
+ * @param {string} toolName - Tool key (e.g. 'claude-code')
+ * @param {Object} storedConfig - The existing integrationConfigs entry
+ * @param {string[]} expectedCategories - Categories computed from current standards
+ * @returns {Object} Config for writeIntegrationFile
+ */
+export function refreshIntegrationConfig(manifest, toolName, storedConfig = {}, expectedCategories = []) {
+  const outputLanguage =
+    manifest.options?.output_language
+    || manifest.options?.commit_language
+    || storedConfig.outputLanguage
+    || storedConfig.commitLanguage
+    || 'english';
+
+  const fresh = buildToolIntegrationConfig(
+    { ...manifest, options: { ...(manifest.options || {}), output_language: outputLanguage } },
+    toolName
+  );
+
+  return {
+    ...storedConfig,
+    ...fresh,
+    tool: toolName,
+    categories: expectedCategories,
+    outputLanguage,
+    format: manifest.format || storedConfig.format || 'ai'
+  };
+}
+
 /**
  * Sync integration file references based on manifest standards
  * @param {string} projectPath - Project path
@@ -1851,6 +2273,16 @@ async function syncIntegrationReferences(projectPath, manifest, { plan = false }
   console.log(chalk.cyan(msg.syncingRefs));
   console.log();
 
+  // Rebuild the config when it is absent rather than sending the user away —
+  // the manifest holds everything it is derived from.
+  if (!manifest.integrationConfigs || Object.keys(manifest.integrationConfigs).length === 0) {
+    const filled = backfillIntegrationConfigs(manifest);
+    if (filled > 0) {
+      console.log(chalk.gray(`  ${(msg.integrationConfigsBackfilled || 'Rebuilt integration config for {count} file(s) from the manifest.').replace('{count}', filled)}`));
+      console.log();
+    }
+  }
+
   // Check if integrationConfigs exists
   if (!manifest.integrationConfigs || Object.keys(manifest.integrationConfigs).length === 0) {
     console.log(chalk.yellow(msg.noIntegrationConfigs));
@@ -1903,14 +2335,9 @@ async function syncIntegrationReferences(projectPath, manifest, { plan = false }
       continue;
     }
 
-    // Regenerate the integration file with updated categories
-    const newConfig = {
-      ...config,
-      tool: toolName,
-      categories: expectedCategories,
-      // Pass output_language for dynamic commit standards generation
-      outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || config.outputLanguage || config.commitLanguage || 'english'
-    };
+    // Regenerate the integration file with updated categories, from the
+    // manifest rather than from the snapshot stored beside it.
+    const newConfig = refreshIntegrationConfig(manifest, toolName, config, expectedCategories);
 
     if (plan) {
       console.log(chalk.yellow(`  ~ ${integrationPath}: categories would change to ${expectedCategories.join(', ') || '(none)'} (dry run — nothing is written)`));
@@ -1930,15 +2357,8 @@ async function syncIntegrationReferences(projectPath, manifest, { plan = false }
         generatedAt: now
       };
 
-      // Update file hash
-      const hashInfo = computeFileHash(fullPath);
-      if (hashInfo) {
-        if (!manifest.fileHashes) {
-          manifest.fileHashes = {};
-        }
-        const normalizedIntPath = integrationPath.replace(/\\/g, '/');
-        manifest.fileHashes[normalizedIntPath] = { ...hashInfo, installedAt: now };
-      }
+      // XSPEC-418 R6: no whole-file fileHashes entry — only the UDS block is
+      // tracked, below.
 
       // Track integration block hash for UDS content integrity
       if (result.blockHashInfo) {
@@ -1958,7 +2378,7 @@ async function syncIntegrationReferences(projectPath, manifest, { plan = false }
 
   // Update manifest version and save
   if (updatedCount > 0) {
-    manifest.version = '3.3.0';
+    bumpManifestVersion(manifest);
     refreshIntegrationBlockHashes(manifest, projectPath);
     if (plan) {
       console.log(chalk.gray('  (dry run — the manifest was not written)'));
@@ -1995,6 +2415,66 @@ async function syncIntegrationReferences(projectPath, manifest, { plan = false }
  * "Write then restore" leaves a broken tree if it dies halfway, which is worse
  * than having no dry run at all — the same reasoning as the integrations plan.
  */
+/**
+ * A general `uds update --plan` (no --skills/--commands scope) never called
+ * planSkills/planCommands — those are the only two places version staleness
+ * is computed, and they only run under `--plan --skills`/`--plan --commands`.
+ * An adopter running plain `--plan` saw a clean reconciliation plan and
+ * nothing else, with Skills or Commands a version behind and no hint that a
+ * scoped plan would have said so. This prints a short, best-effort note —
+ * not a full plan — so the general path is never silent about it.
+ *
+ * Skills staleness is read the same way planSkills does: per-installation,
+ * from what is actually on disk (`getInstalledSkillsInfoForAgent`), 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`, written by every path that installs
+ * commands) against the latest version UDS ships. // implements XSPEC adopter-report Q3
+ *
+ * @param {string} projectPath
+ * @param {Object} manifest
+ */
+function reportStaleSkillsCommandsHint(projectPath, manifest) {
+  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({
+        label: `${getAgentDisplayName(inst.agent)} (${inst.level}): Skills v${current} → v${latestVersion}`,
+        flag: '--skills'
+      });
+    }
+  }
+
+  if (manifest.commands?.installed && (manifest.commands?.installations || []).length > 0) {
+    const current = manifest.commands.version;
+    if (current && current !== latestVersion) {
+      stale.push({
+        label: `Commands: v${current} → v${latestVersion}`,
+        flag: '--commands'
+      });
+    }
+  }
+
+  if (stale.length === 0) return;
+
+  console.log(chalk.yellow('  Skills/Commands installed but out of date:'));
+  for (const s of stale) {
+    console.log(chalk.gray(`    ~ ${s.label}`));
+  }
+  const flags = [...new Set(stale.map((s) => s.flag))];
+  for (const flag of flags) {
+    console.log(chalk.gray(`  Run \`uds update --apply --yes ${flag}\` to update.`));
+  }
+  console.log();
+}
+
 async function planSkills(projectPath, manifest, options) {
   const repoInfo = getRepositoryInfo();
   const latestVersion = repoInfo.skills.version;
@@ -2159,7 +2639,7 @@ async function updateSkillsOnly(projectPath, manifest, options) {
     return;
   }
 
-  const spinner = ora(msg.installingSkills || 'Installing Skills...').start();
+  const spinner = createSpinner(msg.installingSkills || 'Installing Skills...').start();
 
   const skillsLocaleForUpdate = resolveLocale(manifest, projectPath, options);
   const result = await installSkillsToMultipleAgents(
@@ -2283,7 +2763,7 @@ async function updateCommandsOnly(projectPath, manifest, options) {
   }
   console.log();
 
-  const spinner = ora(msg.installingCommands || 'Installing commands...').start();
+  const spinner = createSpinner(msg.installingCommands || 'Installing commands...').start();
 
   const commandsLocale = resolveLocale(manifest, projectPath, options);
   const result = await installCommandsToMultipleAgents(
@@ -2779,8 +3259,8 @@ async function handleRollback(projectPath) {
 /**
  * Handle --plan: show what the reconciler would do without executing.
  */
-async function handlePlan(projectPath, options) {
-  const spinner = ora('Calculating reconciliation plan...').start();
+async function handlePlan(projectPath, options, manifest) {
+  const spinner = createSpinner('Calculating reconciliation plan...').start();
 
   const result = await reconcilerPlan(projectPath, { force: false });
 
@@ -2796,6 +3276,12 @@ async function handlePlan(projectPath, options) {
   console.log(formatPlan(result.plan));
   console.log();
 
+  // XSPEC adopter-report Q3: the reconciliation plan above never covers
+  // Skills/Commands version staleness — only --plan --skills/--commands did.
+  if (manifest) {
+    reportStaleSkillsCommandsHint(projectPath, manifest);
+  }
+
   if (result.plan.actions.length > 0) {
     // NOT `uds update`. That runs the legacy path, which never executes this
     // plan — it refreshes existing standards and reports success for having done
@@ -2855,7 +3341,7 @@ async function handleReconcile(projectPath, options, { force }) {
   }
 
   // Execute
-  const spinner = ora('Applying reconciliation plan...').start();
+  const spinner = createSpinner('Applying reconciliation plan...').start();
 
   const result = await reconcile(projectPath, {
     force,