universal-dev-standards 6.14.0-beta.4 → 6.14.0-beta.5

package/src/commands/audit.js

@@ -345,6 +345,17 @@ async function handleReport(auditResult, options, msg) {
   const isDryRun = options.dryRun || false;
   const forceGh = options.gh || false;
 
+  // XSPEC-454 R3: submitting means talking to GitHub (the `gh` CLI, or a browser/clipboard
+  // fallback). Offline mode must not do that, and must say so — not fail, not skip silently.
+  // A dry run only prints the report, so it still works offline and is offered as the way out.
+  if (options.offline && !isDryRun) {
+    console.log();
+    console.log(chalk.yellow(msg.offlineNoSubmit || 'Offline mode: the report is not submitted.'));
+    console.log(chalk.gray(msg.offlineDryRunHint || '  Use --dry-run to preview it, or run again without --offline to submit.'));
+    console.log();
+    return;
+  }
+
   // Gather findings for selection
   const findings = [];
 

package/src/commands/check.js

@@ -4,7 +4,7 @@ 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 { readManifest, writeManifest, isInitialized, copyStandard, copyIntegration, readPackagedSource } from '../utils/copier.js';
 import {
   getAllStandards,
   getRepositoryInfo, isShippedFilename, resolveStandardFilename, resolveStandardSourcePath } from '../utils/registry.js';
@@ -16,7 +16,7 @@ import {
   computeIntegrationBlockHash,
   pruneIntegrationFileHashes
 } from '../utils/hasher.js';
-import { downloadFromGitHub, getMarketplaceSkillsInfo } from '../utils/github.js';
+import { getMarketplaceSkillsInfo } from '../utils/github.js';
 import {
   getInstalledSkillsInfoForAgent,
   getInstalledCommandsForAgent
@@ -46,6 +46,10 @@ import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
 import { lintAll as lintI18nAll, partitionFindings as partitionI18nFindings } from '../lint/i18n.js';
 import { resolveIntegrationFile } from '../core/constants.js';
 import { checkPreCommitHookWiring } from '../utils/git-hooks.js';
+import { runTestChangeCheck } from '../utils/test-change-check.js';
+import { runTestQualityGates } from '../utils/gate-scripts.js';
+import { pruneForeignSkillHashes, skillIssuesOf } from '../utils/skill-hash-ownership.js';
+import { pruneForeignCommandHashes, projectCommandHashes, commandIssuesOf } from '../utils/command-hash-ownership.js';
 
 /**
  * Display the summary of file integrity status
@@ -413,11 +417,35 @@ export async function checkCommand(options = {}) {
 
   // === Enhanced Integrity Checks (v3.3.0+) ===
 
-  // Check Skills integrity if skillHashes exist
-  checkSkillsIntegrity(manifest, projectPath, msg);
-
-  // Check Commands integrity if commandHashes exist
-  checkCommandsIntegrity(manifest, projectPath, msg);
+  // Check Skills integrity if skillHashes exist.
+  //
+  // XSPEC-454 R2, in this order and no other. Step 1: forget the records that were never UDS's to
+  // keep (the adopter's own skills; `agents/`, `workflows/`, `_shared/` folders an old CLI copied
+  // in and a later update removed). In memory only — `check` is read-only — and `uds update`
+  // drops them from the file. Step 2: what is left is a record of a file UDS installed, so a
+  // missing or changed one is a real finding and counts toward the verdict below. Doing step 2
+  // alone would turn every existing project's `check` (and the pre-commit hook that runs it)
+  // red the day it upgrades, for files nobody can restore.
+  const skillRecordsBefore = Object.keys(manifest.skillHashes || {}).length;
+  pruneForeignSkillHashes(manifest);
+  const ignoredSkillRecords = skillRecordsBefore - Object.keys(manifest.skillHashes || {}).length;
+  const skillsIntegrity = checkSkillsIntegrity(manifest, projectPath, msg, ignoredSkillRecords);
+  const skillIssues = skillIssuesOf(skillsIntegrity);
+
+  // Check Commands integrity if commandHashes exist.
+  //
+  // XSPEC-454 R2, the Commands half, same order as above: first set aside the records this project's
+  // check cannot vouch for (commands UDS does not ship; commands installed at user level, which live
+  // outside the project), then let what is left decide the verdict.
+  const commandRecordsBefore = Object.keys(manifest.commandHashes || {}).length;
+  pruneForeignCommandHashes(manifest);
+  const ignoredCommandRecords = commandRecordsBefore - Object.keys(manifest.commandHashes || {}).length;
+  const projectCommands = projectCommandHashes(manifest);
+  const commandsIntegrity = checkCommandsIntegrity(
+    { ...manifest, commandHashes: projectCommands.hashes }, projectPath, msg,
+    { foreign: ignoredCommandRecords, elsewhere: projectCommands.ignored.length }
+  );
+  const commandIssues = commandIssuesOf(commandsIntegrity);
 
   // XSPEC adopter-report Q3: neither of the two checks above (content-hash
   // integrity) says anything about an installed Skills/Commands version
@@ -465,6 +493,13 @@ export async function checkCommand(options = {}) {
     await showDiff(projectPath, manifest, fileStatus.modified);
     return;
   }
+  if (options.diff) {
+    // Nothing to diff. Say what "nothing" is measured against rather than printing no line at all —
+    // silence reads the same as "the diff step did not run".
+    printDiffBaseline(manifest, msg);
+    console.log(chalk.green(msg.diffNone));
+    console.log();
+  }
 
   // Interactive mode (default when issues detected, only in TTY)
   const hasIssues = fileStatus.modified.length > 0 ||
@@ -513,6 +548,14 @@ export async function checkCommand(options = {}) {
   // pre-commit 檢查檔存在，但 git 實際不會執行它（只報告，不寫入 —— 見 checkPreCommitWiring 下方註解）
   checkPreCommitWiring(projectPath, msg);
 
+  // XSPEC-444 R2 + R5: this commit changes code but no test; fake tests; empty shells.
+  // Warnings by default — a commit is blocked only when the project sets "mode": "block" in
+  // .standards/test-policy.json. Both are read-only here (nothing is written to the project).
+  // XSPEC-454 R2 (same class): both report whether they blocked; in "block" mode they set the exit code
+  // themselves, but the run still ended "compliant" because the verdict below never read what they said.
+  const testChange = runTestChangeCheck(projectPath);
+  const testGates = runTestQualityGates(projectPath);
+
   // Workflow status
   displayWorkflowStatus(projectPath);
 
@@ -520,8 +563,14 @@ export async function checkCommand(options = {}) {
   // 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.
+  // XSPEC-454 R2: the Skills integrity result used to be thrown away (the call above was a bare
+  // statement), so a deleted or edited skill file printed ✗ and still ended in "compliant", exit 0.
   const allGood = fileStatus.missing.length === 0 &&
                   fileStatus.modified.length === 0 &&
+                  skillIssues.length === 0 &&
+                  commandIssues.length === 0 &&
+                  !testChange.blocked &&
+                  !testGates.blocked &&
                   integrationBlockStatus.modified.length === 0 &&
                   integrationBlockStatus.missing.length === 0 &&
                   integrationBlockStatus.noMarkers.length === 0 &&
@@ -530,6 +579,12 @@ export async function checkCommand(options = {}) {
     console.log(chalk.green(msg.projectCompliant));
   } else {
     console.log(chalk.yellow(msg.issuesDetected));
+    if (commandIssues.length > 0) {
+      console.log(chalk.gray(msg.commandsIntegrityFix || '  Command files listed above are missing or were changed: run `uds update --apply --commands` to reinstall them.'));
+    }
+    if (skillIssues.length > 0) {
+      console.log(chalk.gray(msg.skillsIntegrityFix || '  Skill files listed above are missing or were changed: run `uds update --apply --skills` to reinstall them.'));
+    }
     // Set non-zero exit code in CI mode so pipelines detect failures
     if (options.ci) {
       process.exitCode = 1;
@@ -592,6 +647,7 @@ async function interactiveMode(projectPath, manifest, fileStatus, msg) {
 
     switch (action) {
       case 'view': {
+        printDiffBaseline(manifest, msg);
         await showSingleFileDiff(projectPath, manifest, issue.file, msg);
         // After viewing, ask again
         const followUp = await select({
@@ -649,8 +705,33 @@ async function interactiveMode(projectPath, manifest, fileStatus, msg) {
   }
 }
 
+/**
+ * Tell the reader what the diff is measured against (XSPEC-453 R1).
+ *
+ * `uds check --diff` answers "what did I change in what UDS gave me". The original is the copy inside
+ * the installed UDS package, so this says that — and where to look for what UDS itself changed since.
+ * When the project's standards were installed from a different version than the package now installed,
+ * a file UDS changed in between shows up as a difference, so that gap is stated rather than left to be
+ * discovered.
+ */
+function printDiffBaseline(manifest, msg) {
+  const packageVersion = getRepositoryInfo().standards.version;
+  console.log(chalk.gray(msg.diffBaseline.replace('{version}', packageVersion)));
+  const installedVersion = manifest?.upstream?.version;
+  if (installedVersion && installedVersion !== packageVersion) {
+    console.log(chalk.yellow(
+      msg.diffBaselineVersionDiffers.replace('{installed}', installedVersion).replace('{version}', packageVersion)
+    ));
+  }
+}
+
 /**
  * Show diff for a single file
+ *
+ * The original is read from the installed UDS package, never downloaded (XSPEC-453 R1).
+ *
+ * @returns {Promise<'shown'|'no-original'|'unreadable'>} What happened; `'no-original'` means the
+ *   installed package has no original for this file (reported by name, not skipped silently).
  */
 async function showSingleFileDiff(projectPath, manifest, relativePath, msg) {
   const { readFileSync } = await import('fs');
@@ -662,31 +743,31 @@ async function showSingleFileDiff(projectPath, manifest, relativePath, msg) {
     currentContent = readFileSync(fullPath, 'utf-8');
   } catch {
     console.log(chalk.red(msg.couldNotReadFile));
-    return;
+    return 'unreadable';
   }
 
-  // Get original content from GitHub
+  // Get original content from the installed package
   const sourcePath = getSourcePathFromRelative(manifest, relativePath);
   if (!sourcePath) {
     console.log(chalk.red(msg.couldNotDetermineSource2));
-    return;
+    return 'unreadable';
   }
 
-  console.log(chalk.gray(msg.fetchingOriginal));
   let originalContent;
   try {
-    originalContent = await downloadFromGitHub(sourcePath);
+    originalContent = readPackagedSource(sourcePath);
   } catch (error) {
-    if (error.message.includes('429')) {
-      console.log(chalk.red(msg.rateLimited || 'GitHub API rate limit exceeded. Please wait a few minutes and try again.'));
-    } else {
-      console.log(chalk.red(`${msg.couldNotFetchOriginal} (${error.message})`));
-    }
-    return;
+    console.log(chalk.red(`${msg.couldNotReadOriginal.replace('{file}', relativePath)} (${error.message})`));
+    return 'unreadable';
   }
-  if (!originalContent) {
-    console.log(chalk.red(msg.couldNotFetchOriginal));
-    return;
+  if (originalContent === null) {
+    console.log(chalk.red(
+      msg.noOriginalInPackage
+        .replace('{file}', relativePath)
+        .replace('{source}', sourcePath)
+        .replace('{version}', getRepositoryInfo().standards.version)
+    ));
+    return 'no-original';
   }
 
   // Simple diff display
@@ -721,6 +802,7 @@ async function showSingleFileDiff(projectPath, manifest, relativePath, msg) {
     }
   }
   console.log();
+  return 'shown';
 }
 
 /**
@@ -728,11 +810,17 @@ async function showSingleFileDiff(projectPath, manifest, relativePath, msg) {
  */
 async function showDiff(projectPath, manifest, modifiedFiles) {
   const msg = t().commands.check;
+  printDiffBaseline(manifest, msg);
+  let missingOriginals = 0;
   for (const file of modifiedFiles) {
     console.log(chalk.cyan(`\n${msg.diffFor.replace('{file}', file)}`));
     console.log(chalk.gray('─'.repeat(50)));
-    await showSingleFileDiff(projectPath, manifest, file, msg);
+    const outcome = await showSingleFileDiff(projectPath, manifest, file, msg);
+    if (outcome === 'no-original') missingOriginals++;
   }
+  // A package that lacks the original of a file it should have shipped is a defect worth a non-zero
+  // exit: scripts must not read "no diff shown" as "no difference".
+  if (missingOriginals > 0) process.exitCode = 1;
 }
 
 /**
@@ -1916,7 +2004,7 @@ function checkSkillsCommandsVersionStaleness(manifest, projectPath, msg) { // es
  * @param {Object} msg - Localized messages
  * @returns {Object} Status { unchanged: [], modified: [], missing: [] }
  */
-function checkSkillsIntegrity(manifest, projectPath, msg) {
+function checkSkillsIntegrity(manifest, projectPath, msg, ignoredRecords = 0) {
   const skillHashes = manifest.skillHashes;
 
   // Skip if no skill hashes tracked
@@ -1925,6 +2013,10 @@ function checkSkillsIntegrity(manifest, projectPath, msg) {
   }
 
   console.log(chalk.cyan(msg.skillsIntegrityCheck || 'Skills File Integrity'));
+  if (ignoredRecords > 0) {
+    console.log(chalk.gray((msg.skillsStaleRecordsIgnored || '  {count} skill record(s) ignored: they describe files UDS did not install.')
+      .replace('{count}', ignoredRecords)));
+  }
 
   const status = { unchanged: [], modified: [], missing: [], tracked: true };
 
@@ -1987,7 +2079,7 @@ function checkSkillsIntegrity(manifest, projectPath, msg) {
  * @param {Object} msg - Localized messages
  * @returns {Object} Status { unchanged: [], modified: [], missing: [] }
  */
-export function checkCommandsIntegrity(manifest, projectPath, msg) {
+export function checkCommandsIntegrity(manifest, projectPath, msg, ignored = {}) {
   const commandHashes = manifest.commandHashes;
 
   // Skip if no command hashes tracked
@@ -1996,6 +2088,14 @@ export function checkCommandsIntegrity(manifest, projectPath, msg) {
   }
 
   console.log(chalk.cyan(msg.commandsIntegrityCheck || 'Commands File Integrity'));
+  if (ignored.foreign > 0) {
+    console.log(chalk.gray((msg.commandsStaleRecordsIgnored || '  {count} command record(s) ignored: they describe commands UDS does not ship.')
+      .replace('{count}', ignored.foreign)));
+  }
+  if (ignored.elsewhere > 0) {
+    console.log(chalk.gray((msg.commandsElsewhereIgnored || '  {count} command record(s) ignored: those commands are installed at user level, shared by every project.')
+      .replace('{count}', ignored.elsewhere)));
+  }
 
   const status = { unchanged: [], modified: [], missing: [], untracked: [], tracked: true };
 

package/src/commands/init.js

@@ -32,6 +32,7 @@ import { withFileTransaction } from '../utils/transaction.js';
 import { newRecorder, mkdirTracked, recordFile, persistRecorder, RECORD_KINDS } from '../core/install-records.js';
 import { wireGitHooksPath, getLocalHooksPathConfig, stripLegacyHuskyShLine, ensureShebang, hookRunsUdsCheck, buildPreCommitBlock } from '../utils/git-hooks.js';
 import { migrateLegacyHuskyHook } from '../utils/legacy-hook-migration.js';
+import { installGateScripts } from '../utils/gate-scripts.js';
 
 /**
  * Init command - initialize standards in current project
@@ -346,6 +347,21 @@ export async function initCommand(options) {
   for (const created of combinedResults.createdIntegrationFiles ?? []) {
     recordFile(installRecorder, projectPath, created, RECORD_KINDS.INTEGRATION_FILE);
   }
+
+  // 4.8. Ship the fake-test and stub scanners the full-coverage-testing standard asks for
+  // (XSPEC-444 R5). They are written whether or not git is present — the hook step below
+  // needs a repository, the scanners do not — and recorded so `uds uninstall` removes
+  // exactly these files. A file that already exists is the adopter's and is left alone.
+  const gateResult = installGateScripts(projectPath, installRecorder);
+  for (const rel of gateResult.written) {
+    console.log(chalk.green(`  ✓ ${rel} (fake-test / stub scanner — \`uds check\` runs it and warns; edit it freely)`));
+  }
+  for (const rel of gateResult.kept) {
+    console.log(chalk.gray(`  · ${rel} already exists — kept as is`));
+  }
+  for (const file of gateResult.missingTemplate) {
+    console.log(chalk.yellow(`  ⚠ scripts/${file} not installed — the template is missing from this UDS package`));
+  }
   persistRecorder(projectPath, installRecorder);
 
   // 5. Setup Pre-commit Hook

package/src/commands/update.js

@@ -25,6 +25,9 @@ import {
   getToolFromPath
 } from '../utils/reference-sync.js';
 import { checkForUpdates } from '../utils/npm-registry.js';
+import { pruneForeignSkillHashes } from '../utils/skill-hash-ownership.js';
+import { pruneForeignCommandHashes } from '../utils/command-hash-ownership.js';
+import { commandsUpdatedMessage } from '../utils/update-summary.js';
 import { t, setLanguage, isLanguageExplicitlySet } from '../i18n/messages.js';
 import { config } from '../utils/config-manager.js';
 import {
@@ -47,7 +50,8 @@ import {
 import { getMarketplaceSkillsInfo } from '../utils/github.js';
 import { detectAITools } from '../utils/detector.js';
 import { HOOK_CAPABLE_TOOLS, resolveHookTools, installMissingHooks } from '../installers/hooks-installer.js';
-import { persistRecorder, mergeRecorderInto } from '../core/install-records.js';
+import { persistRecorder, mergeRecorderInto, newRecorder } from '../core/install-records.js';
+import { installGateScripts, gateStandardInstalled, GATE_SCRIPTS } from '../utils/gate-scripts.js';
 import { migrateLegacyHuskyHook } from '../utils/legacy-hook-migration.js';
 import {
   promptSkillsInstallLocation,
@@ -58,8 +62,12 @@ import {
   plan as reconcilerPlan,
   rollbackLast,
   formatPlan,
-  listBackups
+  listBackups,
+  createStepBackup,
+  finalizeBackup,
+  cleanupBackups
 } from '../reconciler/index.js';
+import { stepWritePaths } from '../reconciler/install-roots.js';
 import { restoreSingleFile } from './check.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
 import { resolveIntegrationFile, SUPPORTED_AI_TOOLS, getToolFormat } from '../core/constants.js';
@@ -619,6 +627,10 @@ export async function updateCommand(options) {
     // 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);
+    // XSPEC-454 R2: skill records UDS never owned go the same way (an up-to-date adopter is exactly the
+    // one who has nothing else to trigger the correction).
+    const foreignSkillsOnLatest = pruneForeignSkillHashes(manifest);
+    const foreignCommandsOnLatest = pruneForeignCommandHashes(manifest);
     if (retiredOnLatest.length > 0) {
       console.log();
       console.log(chalk.gray(
@@ -627,6 +639,20 @@ export async function updateCommand(options) {
       for (const path of retiredOnLatest) {
         console.log(chalk.gray(`    - ${path}`));
       }
+    }
+    if (foreignSkillsOnLatest.length > 0) {
+      console.log();
+      console.log(chalk.gray(
+        `  ${(msg.droppedForeignSkillHashes || 'Dropped {count} skill record(s) that do not describe files UDS installed.').replace('{count}', foreignSkillsOnLatest.length)}`
+      ));
+    }
+    if (foreignCommandsOnLatest.length > 0) {
+      console.log();
+      console.log(chalk.gray(
+        `  ${(msg.droppedForeignCommandHashes || 'Dropped {count} command record(s) for commands UDS does not ship.').replace('{count}', foreignCommandsOnLatest.length)}`
+      ));
+    }
+    if (retiredOnLatest.length > 0 || foreignSkillsOnLatest.length > 0 || foreignCommandsOnLatest.length > 0) {
       writeManifest(manifest, projectPath);
     }
 
@@ -1139,7 +1165,7 @@ export async function updateCommand(options) {
     manifest.options.coverage_model = manifest.options.coverage_model || 'full-coverage';
     console.log();
     console.log(chalk.yellow(msg.testParadigmMigrated || '⚠ Testing paradigm migrated: pyramid thresholds (UT≥80%/IT≥70%) → behavior-completeness full coverage (XSPEC-178)'));
-    console.log(chalk.cyan(msg.testParadigmNote || '  full-coverage-testing.ai.yaml installed. Review scripts/check-stubs.sh and scripts/check-anti-fake-tests.sh in your project.'));
+    console.log(chalk.cyan(msg.testParadigmNote || '  full-coverage-testing.ai.yaml installed. Review scripts/check-stubs.mjs and scripts/check-anti-fake-tests.mjs in your project (`uds update` offers to write them).'));
   }
 
   // Update manifest
@@ -1657,6 +1683,9 @@ export async function updateCommand(options) {
   // 錯誤訊息單一出口閘門：問過才寫，而且從不覆寫。
   await offerErrorExitGate(projectPath, options);
 
+  // 假測試與空殼掃描（XSPEC-444 R5）：同樣問過才寫、從不覆寫。
+  await offerTestQualityGates(projectPath, options);
+
   // Exit explicitly to prevent hanging.
   // T11: a partial update exits non-zero so CI / scripts can detect the failure.
   process.exit(updateIncomplete ? 1 : 0);
@@ -1706,6 +1735,47 @@ async function offerErrorExitGate(projectPath, options) {
   console.log();
 }
 
+/**
+ * Offer the fake-test and stub scanners to an EXISTING installation.
+ * // implements XSPEC-444 R5
+ *
+ * `uds init` writes them for a new project. A project initialised before that has the
+ * full-coverage-testing standard — which asks for these two scripts — but never received them.
+ * Writing files into a repository nobody asked us to touch is a trust problem, so this shows
+ * what is about to be written, asks (default: no), and never overwrites a file that exists.
+ */
+async function offerTestQualityGates(projectPath, options) {
+  if (!gateStandardInstalled(projectPath)) return;
+  const wanted = GATE_SCRIPTS.filter(({ file }) => !existsSync(join(projectPath, 'scripts', file)));
+  if (wanted.length === 0) return;
+  const available = wanted.filter(({ file }) => existsSync(join(getRepoRoot(), 'templates', 'gates', file)));
+  if (available.length === 0) return; // templates not shipped in this package — stay silent, do not pretend
+
+  console.log(chalk.bold('  Fake-test and stub scanners'));
+  console.log(chalk.gray('    The full-coverage-testing standard asks for these scripts; this project does not have them yet:'));
+  for (const { file, what } of available) console.log(chalk.gray(`      - scripts/${file}  (finds ${what})`));
+  console.log(chalk.gray('    Pure Node, no dependencies. `uds check` runs them and prints what they find as a WARNING;'));
+  console.log(chalk.gray('    nothing is blocked unless you set "mode": "block" in .standards/test-policy.json.'));
+  console.log();
+
+  const ok = await confirmOrFail({
+    message: 'Write these scripts into scripts/ ?',
+    defaultValue: false, // silence is not consent
+    options
+  });
+  if (!ok) {
+    console.log(chalk.gray('  Skipped. `uds check` will mention it again, but never writes them on its own.'));
+    console.log();
+    return;
+  }
+  const recorder = newRecorder();
+  const result = installGateScripts(projectPath, recorder);
+  persistRecorder(projectPath, recorder);
+  for (const rel of result.written) console.log(chalk.green(`  ✓ ${rel}`));
+  for (const rel of result.kept) console.log(chalk.gray(`  · ${rel} already exists — kept as is`));
+  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.
@@ -2800,6 +2870,16 @@ async function updateSkillsOnly(projectPath, manifest, options) {
     return;
   }
 
+  // XSPEC-454 R1: this step writes outside the reconciler, so it takes its own rollback point — the skill
+  // folders UDS ships, in each project-level skills folder (new ones are created, old ones rewritten, and
+  // `.manifest.json` replaced), and nothing else: the adopter's own skills are not UDS's to roll back.
+  // No backup, no write: an install that cannot be undone must not start.
+  const skillsBackup = takeStepBackup(projectPath, 'skills', fileBasedInstallations, 'skills');
+  if (!skillsBackup.ok) {
+    process.exit(1);
+    return;
+  }
+
   const spinner = createSpinner(msg.installingSkills || 'Installing Skills...').start();
 
   const skillsLocaleForUpdate = resolveLocale(manifest, projectPath, options);
@@ -2845,6 +2925,9 @@ async function updateSkillsOnly(projectPath, manifest, options) {
     if (!manifest.skillHashes) manifest.skillHashes = {};
     Object.assign(manifest.skillHashes, result.allFileHashes);
   }
+  // XSPEC-454 R2: and forget the records that were never UDS's (the manifest this merges into
+  // may come from an installer that hashed the whole skills folder).
+  pruneForeignSkillHashes(manifest);
 
   // 🔴 Re-read before writing. `manifest` was loaded at the top of the update
   // command, BEFORE the reconciler ran; the reconciler writes its own copy to
@@ -2866,6 +2949,7 @@ async function updateSkillsOnly(projectPath, manifest, options) {
   freshForSkills.skills = manifest.skills;
   freshForSkills.skillHashes = manifest.skillHashes;
   writeManifest(freshForSkills, projectPath);
+  finishStepBackup(projectPath, skillsBackup);
 
   console.log();
   process.exit(0);
@@ -2924,6 +3008,13 @@ async function updateCommandsOnly(projectPath, manifest, options) {
   }
   console.log();
 
+  // XSPEC-454 R1: same as the Skills step — a rollback point first, and no write without one.
+  const commandsBackup = takeStepBackup(projectPath, 'commands', commandsInstallations, 'commands');
+  if (!commandsBackup.ok) {
+    process.exit(1);
+    return;
+  }
+
   const spinner = createSpinner(msg.installingCommands || 'Installing commands...').start();
 
   const commandsLocale = resolveLocale(manifest, projectPath, options);
@@ -2944,9 +3035,8 @@ async function updateCommandsOnly(projectPath, manifest, options) {
   }).join(', ');
 
   if (result.totalErrors === 0) {
-    spinner.succeed((msg.commandsUpdated || 'Updated {count} commands: {locations}')
-      .replace('{count}', result.totalInstalled)
-      .replace('{locations}', locations));
+    // XSPEC-454 R4: tools and commands are different numbers; see commandsUpdatedMessage.
+    spinner.succeed(commandsUpdatedMessage(msg, commandsInstallations, result, locations));
   } else {
     spinner.warn((msg.commandsUpdatedWithErrors || 'Updated commands with {errors} errors')
       .replace('{errors}', result.totalErrors));
@@ -2971,6 +3061,8 @@ async function updateCommandsOnly(projectPath, manifest, options) {
     if (!manifest.commandHashes) manifest.commandHashes = {};
     replaceCommandHashesForUpdatedAgents(manifest.commandHashes, result.allFileHashes);
   }
+  // XSPEC-454 R2: and forget command records for commands UDS does not ship.
+  pruneForeignCommandHashes(manifest);
 
   // 🔴 Re-read before writing. `manifest` was loaded at the top of the update
   // command, BEFORE the reconciler ran; the reconciler writes its own copy to
@@ -2994,6 +3086,7 @@ async function updateCommandsOnly(projectPath, manifest, options) {
   freshForCommands.commands = manifest.commands;
   freshForCommands.commandHashes = manifest.commandHashes;
   writeManifest(freshForCommands, projectPath);
+  finishStepBackup(projectPath, commandsBackup);
 
   console.log();
   process.exit(0);
@@ -3386,7 +3479,47 @@ async function promptNewFeatureInstallation(missingSkills, outdatedSkills, missi
 // ─── DSR (Declarative State Reconciliation) Handlers ─────────────
 
 /**
- * Handle --rollback: restore from the most recent backup.
+ * Take the rollback point for a Skills/Commands step (XSPEC-454 R1).
+ * Prints what it did; `ok: false` means the caller must not write anything.
+ */
+function takeStepBackup(projectPath, label, installations, kind) {
+  const { paths, outside } = stepWritePaths(projectPath, installations, kind);
+  const backup = createStepBackup(projectPath, { label, paths, notBackedUp: outside });
+  if (backup.errors.length > 0) {
+    console.log(chalk.red(`Could not take a backup before updating ${label}; nothing was changed.`));
+    for (const err of backup.errors) console.log(chalk.red(`  ${err}`));
+    console.log();
+    return { ok: false };
+  }
+  cleanupBackupsQuietly(projectPath);
+  return { ok: true, backupId: backup.backupId };
+}
+
+/** The step is over (its last manifest write is done): record what it created, and say how to undo it. */
+function finishStepBackup(projectPath, backup) {
+  finalizeBackup(projectPath, backup.backupId);
+  console.log(chalk.gray(`  Backup: ${backup.backupId}`));
+  console.log(chalk.gray('  Use `uds update --rollback` to undo.'));
+}
+
+function cleanupBackupsQuietly(projectPath) {
+  try {
+    cleanupBackups(projectPath);
+  } catch {
+    // an old backup that cannot be removed is not a reason to stop the update
+  }
+}
+
+/** Print up to `limit` paths, then how many more. */
+function printPaths(prefix, paths, limit, colour) {
+  for (const p of paths.slice(0, limit)) console.log(colour(`  ${prefix} ${p}`));
+  if (paths.length > limit) console.log(colour(`  ${prefix} … and ${paths.length - limit} more`));
+}
+
+/**
+ * Handle --rollback: undo the newest backup and every earlier one from the same unbroken series of UDS
+ * updates, then say, item by item, what was restored, what was removed, and what was NOT put back.
+ * It never ends in "successful" while any of those lists is not empty (XSPEC-454 R1).
  */
 async function handleRollback(projectPath) {
   const backups = listBackups(projectPath);
@@ -3397,22 +3530,46 @@ async function handleRollback(projectPath) {
   }
 
   const latest = backups[0];
-  console.log(chalk.cyan(`Rolling back to: ${latest.backupId}`));
+  console.log(chalk.cyan(`Rolling back from: ${latest.backupId}`));
   console.log(chalk.gray(`  Created: ${latest.createdAt}`));
-  console.log(chalk.gray(`  Actions: ${latest.actionCount}`));
   console.log();
 
   const result = rollbackLast(projectPath);
-  if (result.success) {
-    console.log(chalk.green(`Rollback successful. Restored ${result.restored.length} files.`));
-    for (const file of result.restored) {
-      console.log(chalk.gray(`  ← ${file}`));
-    }
-  } else {
-    console.log(chalk.red('Rollback failed:'));
-    for (const err of result.errors) {
-      console.log(chalk.red(`  ${err}`));
-    }
+
+  for (const step of result.steps || []) {
+    console.log(chalk.cyan(`${step.backupId}${step.label ? ` (${step.label})` : ''}`));
+    console.log(chalk.gray(`  Restored ${step.restored.length} file(s), removed ${step.removed.length} file(s) the update had created.`));
+    printPaths('←', step.restored, 12, chalk.gray);
+    printPaths('✕', step.removed, 12, chalk.gray);
+  }
+  if (!result.steps) {
+    // a rollbackLast that predates the step report
+    printPaths('←', result.restored || [], 12, chalk.gray);
+  }
+  console.log();
+
+  if ((result.steps || []).length > 1) {
+    console.log(chalk.gray(`  ${result.steps.length} consecutive updates were undone together (each one started from where the previous one ended).`));
+  }
+  if (result.olderBackups > 0) {
+    console.log(chalk.gray(`  ${result.olderBackups} older backup(s) are not part of that series (something else changed the project in between) and were left alone.`));
+  }
+
+  if (result.errors.length > 0) {
+    process.exitCode = 1;
+    console.log(chalk.red('Rollback did NOT complete. The project may be in a mixed state:'));
+    printPaths('✗', result.errors, 30, chalk.red);
+    console.log(chalk.yellow('  What to do: fix the cause above (permissions, a locked file) and run `uds update --rollback` again —'));
+    console.log(chalk.yellow('  it is safe to repeat. The backups are still in .uds-backup-* if you need to copy files back by hand.'));
+  }
+  if ((result.notRestored || []).length > 0) {
+    console.log(chalk.yellow('Not restored:'));
+    printPaths('!', result.notRestored, 30, chalk.yellow);
+  }
+  if (result.errors.length === 0 && (result.notRestored || []).length === 0) {
+    console.log(chalk.green(`Rollback successful. Restored ${result.restored.length} file(s), removed ${(result.removed || []).length}.`));
+  } else if (result.errors.length === 0) {
+    console.log(chalk.yellow('Rollback finished for everything inside this project, except the items listed above.'));
   }
   console.log();
 }
@@ -3480,6 +3637,10 @@ async function handleReconcile(projectPath, options, { force }) {
   const planResult = await reconcilerPlan(projectPath, { force });
 
   if (planResult.plan.actions.length === 0) {
+    // XSPEC-454 R2: nothing to apply, but the manifest may still list skill files UDS never installed
+    // (they only ever get corrected by a write, and an up-to-date project has none coming).
+    const current = readManifest(projectPath);
+    if (current && (pruneForeignSkillHashes(current).length + pruneForeignCommandHashes(current).length) > 0) writeManifest(current, projectPath);
     console.log(chalk.green('Everything is up to date. No changes needed.'));
     console.log();
     return;