universal-dev-standards 6.10.0 → 6.12.0

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
   };
 }
 

package/src/commands/update.js

@@ -6,10 +6,11 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from '
 import { join, basename, dirname, relative } from 'path';
 import { readManifest, writeManifest, copyStandard, isInitialized, getRepoRoot } from '../utils/copier.js';
 import { getRepositoryInfo, getAllStandards, getShippableFilenames, getStandardSource } from '../utils/registry.js';
-import { computeFileHash, planStandardsRemovals, refreshIntegrationBlockHashes } from '../utils/hasher.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, SUPPORTED_AI_TOOLS } 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';
 
 /**
@@ -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);
@@ -752,6 +764,16 @@ export async function updateCommand(options) {
 
   // Update integrations (unless --standards-only)
   if (!options.standardsOnly && manifest.integrations && manifest.integrations.length > 0) {
+    // 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
@@ -773,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)
       }
@@ -790,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);
@@ -849,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.
@@ -880,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
     }
   }
 
@@ -951,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)
@@ -1086,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];
@@ -1119,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);
     }
@@ -1641,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
@@ -1665,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);
@@ -1678,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) {
@@ -1726,6 +1895,14 @@ export function regenerateIntegrations(projectPath, manifest) {
     }
   }
 
+  // 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,
@@ -1793,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';
@@ -1822,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);
@@ -1831,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}`));
@@ -1854,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);
 
@@ -1897,7 +2091,10 @@ export function backfillIntegrationConfigs(manifest) {
   const tools = manifest.aiTools?.length ? manifest.aiTools : [];
   const byFile = new Map();
   for (const tool of tools) {
-    const file = resolveIntegrationFile(tool) || getToolFilePath(tool);
+    // 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.
@@ -1943,6 +2140,14 @@ function resolveToolKeyFromEntry(entry) {
  * 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
@@ -2152,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) {
@@ -2180,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)'));
@@ -2217,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;
@@ -3001,7 +3259,7 @@ async function handleRollback(projectPath) {
 /**
  * Handle --plan: show what the reconciler would do without executing.
  */
-async function handlePlan(projectPath, options) {
+async function handlePlan(projectPath, options, manifest) {
   const spinner = createSpinner('Calculating reconciliation plan...').start();
 
   const result = await reconcilerPlan(projectPath, { force: false });
@@ -3018,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

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