universal-dev-standards 6.9.0 → 6.11.0

package/src/commands/check.js

@@ -1,18 +1,20 @@
 import chalk from 'chalk';
 import { select } from '@inquirer/prompts';
-import ora from 'ora';
+import { createSpinner } from '../utils/spinner.js';
 import { existsSync, readFileSync } from 'fs';
 import { join, basename } from 'path';
 import { execSync } from 'child_process';
 import { readManifest, writeManifest, isInitialized, copyStandard, copyIntegration } from '../utils/copier.js';
 import {
   getAllStandards,
-  getRepositoryInfo, resolveStandardFilename, resolveStandardSourcePath } from '../utils/registry.js';
+  getRepositoryInfo, isShippedFilename, resolveStandardFilename, resolveStandardSourcePath } from '../utils/registry.js';
 import {
   computeFileHash,
   compareFileHash,
   hasFileHashes,
-  compareIntegrationBlockHash
+  compareIntegrationBlockHash,
+  computeIntegrationBlockHash,
+  pruneIntegrationFileHashes
 } from '../utils/hasher.js';
 import { downloadFromGitHub, getMarketplaceSkillsInfo } from '../utils/github.js';
 import {
@@ -27,9 +29,12 @@ import {
 } from '../config/ai-agent-paths.js';
 import {
   parseReferences,
+  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';
@@ -60,6 +65,19 @@ function displayFileIntegritySummary(fileStatus, msg) {
     }
   }
 
+  // Reported apart from `missing`, and in grey rather than red, because the
+  // adopter who sees this did what the migration guide asked. The remedy named
+  // here is the one that works: `--restore` cannot resolve a source for any of
+  // them, and used to be the only thing offered.
+  if (fileStatus.retired?.length > 0) {
+    console.log();
+    console.log(chalk.gray(`  ${(msg.retiredHeader || '{count} tracked file(s) are no longer shipped by UDS:').replace('{count}', fileStatus.retired.length)}`));
+    for (const file of fileStatus.retired) {
+      console.log(chalk.gray(`  - ${file} (${msg.retired || 'no longer shipped by UDS'})`));
+    }
+    console.log(chalk.gray(`    ${msg.retiredHint || 'Run `uds update --prune` to drop their manifest entries.'}`));
+  }
+
   if (fileStatus.noHash.length > 0) {
     for (const file of fileStatus.noHash) {
       console.log(chalk.gray(`  ? ${file} (${msg.existsNoHash})`));
@@ -71,10 +89,39 @@ function displayFileIntegritySummary(fileStatus, msg) {
     .replace('{unchanged}', fileStatus.unchanged.length)
     .replace('{modified}', fileStatus.modified.length)
     .replace('{missing}', fileStatus.missing.length)}` +
+    (fileStatus.retired?.length > 0 ? `, ${fileStatus.retired.length} ${msg.retired || 'no longer shipped'}` : '') +
     (fileStatus.noHash.length > 0 ? `, ${fileStatus.noHash.length} no hash` : '')));
   console.log();
 }
 
+/**
+ * A file `fileHashes` tracks has gone. Is that a problem, or is it the migration
+ * guide's instruction carried out?
+ *
+ * MIGRATION-v6 §2 told adopters to delete the seven descoped `.ai.yaml` copies
+ * by hand. Doing so left the hash entries behind, and this check called each one
+ * `missing` and offered `uds check --restore` — a restore that then failed on
+ * every one with "could not determine source", because there has been no source
+ * upstream since 6.0.0. The tool asked the user to undo its own documentation,
+ * using a command it already knew could not work.
+ *
+ * The distinguishing question is whether UDS still ships a file by that name,
+ * which is the registry's to answer, not the manifest's. Anything outside
+ * `.standards/` is never retired: integration files are generated, not shipped
+ * under a standard's name, so a missing CLAUDE.md is exactly what it looks like.
+ *
+ * @param {string} relativePath - Path as recorded in fileHashes
+ * @param {Object} manifest - Project manifest (unused today; kept so callers
+ *   need not know whether the answer depends on project state)
+ * @returns {'missing'|'retired'}
+ */
+export function classifyMissingFile(relativePath, manifest) { // eslint-disable-line no-unused-vars
+  const normalized = String(relativePath).replace(/\\/g, '/');
+  if (!normalized.startsWith('.standards/')) return 'missing';
+  const fileName = normalized.split('/').pop();
+  return isShippedFilename(fileName) ? 'missing' : 'retired';
+}
+
 /**
  * Perform integrity check for standards and integration files
  * @returns {Object} File status object
@@ -84,12 +131,29 @@ function performFileIntegrityCheck(projectPath, manifest, msg) {
     unchanged: [],
     modified: [],
     missing: [],
+    // Tracked, gone, and gone on purpose: UDS stopped shipping it. Counted
+    // apart from `missing` so the summary line stops calling a completed
+    // migration a fault.
+    retired: [],
     noHash: []
   };
 
   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);
 
@@ -101,7 +165,7 @@ function performFileIntegrityCheck(projectPath, manifest, msg) {
           fileStatus.modified.push(relativePath);
           break;
         case 'missing':
-          fileStatus.missing.push(relativePath);
+          fileStatus[classifyMissingFile(relativePath, manifest)].push(relativePath);
           break;
       }
     }
@@ -354,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;
   }
 
@@ -423,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 {
@@ -537,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();
@@ -654,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();
@@ -681,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;
     }
@@ -703,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 {
@@ -723,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
  */
@@ -871,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)));
@@ -1151,19 +1344,39 @@ function checkIntegrationFiles(manifest, projectPath, msg) {
   // After migrateStandardsPathsToIds(), manifest.standards contains IDs, so a plain
   // content.includes(id) check would fail for these mismatched entries.
   const allRegistryStds = getAllStandards();
-  const idToAiFilename = new Map(
-    allRegistryStds
-      .filter(s => s.source?.ai)
-      .map(s => [s.id, basename(s.source.ai)])
+  // 🔴 `source` is a string for some entries and an object for others. Reading
+  // `s.source.ai` on a string yields undefined, so `zh-tw-locale`
+  // (source: 'extensions/locales/zh-tw.md') fell out of this map and the file it
+  // installs — `.standards/zh-tw.md` — was never recognised: "67/68 項標準已參考,
+  // 缺少: zh-tw-locale" on a project whose index lists it (reported 2026-09-16).
+  const idToFilenames = new Map(
+    allRegistryStds.map(s => {
+      const sources = typeof s.source === 'string'
+        ? [s.source]
+        : [s.source?.ai, s.source?.human].filter(Boolean);
+      return [s.id, sources.map(src => basename(src))];
+    })
   );
 
   let hasIssues = false;
   let checkedCount = 0;
 
+  // codex and opencode both write AGENTS.md, so iterating tools printed the same
+  // file twice with identical verdicts (reported 2026-09-16). One file, one
+  // verdict — the tools that share it are named on the line instead.
+  const toolsByFile = new Map();
   for (const tool of manifest.aiTools) {
-    const toolFile = getToolFilePath(tool);
-    if (!toolFile) continue;
+    // 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);
+  }
 
+  for (const [toolFile, sharingTools] of toolsByFile) {
+    const tool = sharingTools[0];
+    const sharedSuffix = sharingTools.length > 1 ? ` (${sharingTools.join(', ')})` : '';
     const fullPath = join(projectPath, toolFile);
 
     // Check if file exists
@@ -1186,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');
@@ -1201,9 +1427,9 @@ function checkIntegrationFiles(manifest, projectPath, msg) {
       // migration. For standards where the ID doesn't match the .ai.yaml basename
       // (e.g. ID "error-code-standards" → file "error-codes.ai.yaml"), we must
       // also check the actual filename so those aren't falsely reported as missing.
-      const aiFilename = idToAiFilename.get(stdFile);
+      const filenames = idToFilenames.get(stdFile) || [];
       const isReferenced = content.includes(stdFile) ||
-        (aiFilename !== undefined && aiFilename !== stdFile && content.includes(aiFilename)) ||
+        filenames.some(name => name !== stdFile && content.includes(name)) ||
         content.includes(`.standards/${stdFile}`) ||
         content.includes(`standards/${stdFile}`);
 
@@ -1224,7 +1450,7 @@ function checkIntegrationFiles(manifest, projectPath, msg) {
     const declaredCount = parseStandardsIndexCount(content);
     if (declaredCount !== null) {
       if (declaredCount === totalTrackable) {
-        console.log(chalk.green(`  ✓ ${toolFile}:`));
+        console.log(chalk.green(`  ✓ ${toolFile}${sharedSuffix}:`));
         console.log(chalk.gray(`    ${msg.standardsIndexPresent}`));
         console.log(chalk.gray(`    ${msg.standardsIndexCount
           ? msg.standardsIndexCount.replace('{count}', declaredCount)
@@ -1404,9 +1630,12 @@ function checkReferenceSync(manifest, projectPath, msg) {
     }
 
     const references = parseReferences(content);
-    if (references.length === 0) continue;
+    // Whole-file scan, separate from reference sync: the paths that matter here
+    // are the ones outside the UDS block, which no generation ever revisits.
+    const brokenMentions = findBrokenPathMentions(content, projectPath);
+    if (references.length === 0 && brokenMentions.length === 0) continue;
 
-    results.push({ integrationPath, references });
+    results.push({ integrationPath, references, brokenMentions });
   }
 
   // Skip entire section if no files have references
@@ -1416,14 +1645,42 @@ function checkReferenceSync(manifest, projectPath, msg) {
 
   let hasIssues = false;
 
-  for (const { integrationPath, references } of results) {
+  for (const { integrationPath, references, brokenMentions } of results) {
+    // Paths mentioned anywhere in the file that resolve to nothing. Reported
+    // first and separately from reference sync, because these are usually
+    // outside the UDS markers — left by an older `uds init`, never revisited by
+    // any regeneration, and followed by an AI tool that then finds nothing.
+    if (brokenMentions?.length > 0) {
+      hasIssues = true;
+      console.log(chalk.red(`  ✗ ${integrationPath}:`));
+      console.log(chalk.red(`    ${msg.brokenMentions || 'mentions paths that do not exist in this project:'}`));
+      for (const path of brokenMentions) {
+        console.log(chalk.red(`      - ${path}`));
+      }
+      console.log(chalk.gray(`    ${msg.brokenMentionsFix || 'These are usually outside the UDS block and must be corrected by hand; UDS does not rewrite text it did not write.'}`));
+    }
+
     // Compare with manifest standards
-    const { orphanedRefs, missingRefs, syncedRefs } = compareStandardsWithReferences(
+    const { orphanedRefs, missingRefs, syncedRefs, danglingRefs } = compareStandardsWithReferences(
       manifest.standards,
-      references
+      references,
+      { projectPath, options: manifest.options }
     );
 
     // Report results
+    // 🔴 A reference to a file that is not on disk is the one failure an AI tool
+    // cannot work around: it follows the link and finds nothing. Reported before
+    // the manifest-level findings because it needs no interpretation.
+    if (danglingRefs.length > 0) {
+      hasIssues = true;
+      console.log(chalk.red(`  ✗ ${integrationPath}:`));
+      console.log(chalk.red(`    ${msg.danglingRefs || 'references files that do not exist:'}`));
+      for (const ref of danglingRefs) {
+        console.log(chalk.red(`      - .standards/${ref}`));
+      }
+      console.log(chalk.gray(`    ${msg.danglingRefsFix || 'Run `uds update --integrations-only` to regenerate them.'}`));
+    }
+
     if (orphanedRefs.length > 0) {
       hasIssues = true;
       console.log(chalk.yellow(`  ⚠ ${integrationPath}:`));
@@ -1442,14 +1699,21 @@ function checkReferenceSync(manifest, projectPath, msg) {
       }
     }
 
-    if (orphanedRefs.length === 0 && missingRefs.length === 0) {
+    if (orphanedRefs.length === 0 && missingRefs.length === 0 && danglingRefs.length === 0) {
       console.log(chalk.green(`  ✓ ${msg.refsInSync.replace('{path}', integrationPath).replace('{count}', syncedRefs.length)}`));
     }
   }
 
   if (hasIssues) {
     console.log();
-    console.log(chalk.yellow(`  ${msg.runSyncRefs}`));
+    // `uds update --sync-refs` refuses to run without `integrationConfigs`, and a
+    // project initialised non-interactively never had that key — so this hint
+    // named a command that could not work (reproduced on a clean 6.9.0 project,
+    // 2026-09-16). Name the one that regenerates from the manifest instead.
+    const canSyncRefs = manifest.integrationConfigs && Object.keys(manifest.integrationConfigs).length > 0;
+    console.log(chalk.yellow(`  ${canSyncRefs
+      ? msg.runSyncRefs
+      : (msg.runIntegrationsOnly || 'Run `uds update --integrations-only` to regenerate integration files.')}`));
   }
 
   console.log();
@@ -1461,7 +1725,7 @@ function checkReferenceSync(manifest, projectPath, msg) {
  */
 async function checkCliVersion(bundledVersion) {
   const msg = t().commands.check;
-  const spinner = ora({ text: msg.checkingCliUpdates, spinner: 'dots' }).start();
+  const spinner = createSpinner({ text: msg.checkingCliUpdates, spinner: 'dots' }).start();
 
   try {
     const result = await checkForUpdates(bundledVersion, {
@@ -1504,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
@@ -1582,17 +1899,17 @@ function checkSkillsIntegrity(manifest, projectPath, msg) {
  * @param {Object} msg - Localized messages
  * @returns {Object} Status { unchanged: [], modified: [], missing: [] }
  */
-function checkCommandsIntegrity(manifest, projectPath, msg) {
+export function checkCommandsIntegrity(manifest, projectPath, msg) {
   const commandHashes = manifest.commandHashes;
 
   // Skip if no command hashes tracked
   if (!commandHashes || Object.keys(commandHashes).length === 0) {
-    return { unchanged: [], modified: [], missing: [], tracked: false };
+    return { unchanged: [], modified: [], missing: [], untracked: [], tracked: false };
   }
 
   console.log(chalk.cyan(msg.commandsIntegrityCheck || 'Commands File Integrity'));
 
-  const status = { unchanged: [], modified: [], missing: [], tracked: true };
+  const status = { unchanged: [], modified: [], missing: [], untracked: [], tracked: true };
 
   for (const [hashKey, hashInfo] of Object.entries(commandHashes)) {
     // Parse key format: agent/filename.md
@@ -1632,8 +1949,42 @@ function checkCommandsIntegrity(manifest, projectPath, msg) {
     }
   }
 
+  // 🔴 The loop above measures only what the manifest happens to track. When a
+  // partial apply dropped 48 of 51 entries (6.9.0, fixed in plan-executor.js),
+  // this section printed "All command files intact (3 files)" while the adoption
+  // summary printed "Commands: 51 installed" from a directory listing — two
+  // numbers, two sources, never compared, so the gap read as a pass.
+  const trackedKeys = new Set(Object.keys(commandHashes));
+  const agentsToScan = new Set(Object.keys(commandHashes).map(k => k.split('/')[0]));
+  for (const entry of manifest.commands?.installations || []) {
+    const agentName = typeof entry === 'string' ? entry : entry?.agent;
+    if (agentName) agentsToScan.add(agentName);
+  }
+  for (const agentName of agentsToScan) {
+    // Reuse the installer's own listing so this file filter cannot drift from it.
+    const info = getInstalledCommandsForAgent(agentName, 'project', projectPath);
+    if (!info?.installed) continue;
+    const ext = agentName === 'gemini-cli' ? '.toml' : '.md';
+    for (const name of info.commands || []) {
+      const key = `${agentName}/${name}${ext}`;
+      if (!trackedKeys.has(key)) status.untracked.push(key);
+    }
+  }
+  if (status.untracked.length > 0) {
+    console.log(chalk.yellow(`  ⚠ ${(msg.commandsUntracked || '{count} installed command file(s) are covered by no hash — integrity is not checked for them')
+      .replace('{count}', status.untracked.length)}`));
+    for (const key of status.untracked.slice(0, 5)) {
+      console.log(chalk.yellow(`      - ${key}`));
+    }
+    if (status.untracked.length > 5) {
+      console.log(chalk.yellow(`      … +${status.untracked.length - 5}`));
+    }
+    console.log(chalk.gray(`  ${msg.commandsUntrackedFix || 'Run `uds update --commands` to record them again.'}`));
+  }
+
+
   // Summary
-  if (status.modified.length === 0 && status.missing.length === 0) {
+  if (status.modified.length === 0 && status.missing.length === 0 && status.untracked.length === 0) {
     console.log(chalk.green(`  ✓ ${msg.allCommandsIntact || 'All command files intact'} (${status.unchanged.length} files)`));
   } else {
     console.log(chalk.gray(`  ${(msg.commandsIntegritySummary || '{unchanged} unchanged, {modified} modified, {missing} missing')
@@ -1652,19 +2003,19 @@ 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);
@@ -1676,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':
@@ -1698,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'}`));
     }
   }