universal-dev-standards 6.8.0 → 6.10.0

package/src/commands/update.js

@@ -1,12 +1,12 @@
 import chalk from 'chalk';
-import ora from 'ora';
+import { createSpinner } from '../utils/spinner.js';
 import { select, confirm as inquirerConfirm, checkbox, Separator } from '@inquirer/prompts';
 import { execSync } from 'child_process';
-import { existsSync, readFileSync, unlinkSync } from 'fs';
-import { join, basename } from 'path';
-import { readManifest, writeManifest, copyStandard, isInitialized } from '../utils/copier.js';
-import { getRepositoryInfo, getAllStandards, getStandardSource } from '../utils/registry.js';
-import { computeFileHash, scanForUntrackedFiles, refreshIntegrationBlockHashes } from '../utils/hasher.js';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { join, basename, dirname, relative } from 'path';
+import { readManifest, writeManifest, copyStandard, isInitialized, getRepoRoot } from '../utils/copier.js';
+import { getRepositoryInfo, getAllStandards, getShippableFilenames, getStandardSource } from '../utils/registry.js';
+import { computeFileHash, planStandardsRemovals, refreshIntegrationBlockHashes } from '../utils/hasher.js';
 import {
   writeIntegrationFile,
   getToolFilePath,
@@ -42,6 +42,7 @@ import {
   getCommandsDirForAgent
 } from '../config/ai-agent-paths.js';
 import { getMarketplaceSkillsInfo } from '../utils/github.js';
+import { detectAITools } from '../utils/detector.js';
 import {
   promptSkillsInstallLocation,
   promptCommandsInstallation
@@ -55,8 +56,111 @@ import {
 } from '../reconciler/index.js';
 import { restoreSingleFile } from './check.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
-import { resolveIntegrationFile } from '../core/constants.js';
-import { mergeInstalledNames } from '../core/manifest.js';
+import { resolveIntegrationFile, SUPPORTED_AI_TOOLS } from '../core/constants.js';
+import {
+  mergeInstalledNames,
+  recordFileProvenance,
+  forgetFileProvenance,
+  establishProvenance,
+  isProvenanceEstablished
+} from '../core/manifest.js';
+
+/**
+ * How aggressive `uds update` is about deleting standards it no longer ships.
+ *
+ * XSPEC-384 §4 leaves the staging strategy for R2 undecided, so this is the
+ * most conservative of the three options on the table and it lives in one named
+ * place rather than being spread through the deletion path. Changing this
+ * constant is the whole change of default; the alternatives are:
+ *
+ *   'report-only'  list what would go, delete nothing without --prune  (current)
+ *   'ask'          list, and prompt in interactive sessions only
+ *   'auto'         delete as part of a normal update
+ *
+ * It starts at 'report-only' because the change is adopter-visible in the
+ * dangerous direction: files that survive today start disappearing. A default
+ * that deletes must not arrive in a patch release, and must not arrive at all
+ * before someone decides it should.
+ */
+export const PRUNE_POLICY = 'report-only';
+
+/**
+ * Decide whether this run is allowed to delete.
+ *
+ * `--prune` is deliberately its own flag rather than a use of `--yes`. `--yes`
+ * means "don't ask me about the thing I already asked for"; it is set in CI and
+ * in scripts, and letting it also authorise deletion would enable the
+ * destructive path silently in exactly the unattended environments that cannot
+ * notice it. Non-interactive runs therefore never delete unless --prune is
+ * explicit. (XSPEC-384 R3)
+ *
+ * @param {Object} plan - Result of planStandardsRemovals
+ * @param {Object} options - Command options
+ * @returns {boolean}
+ */
+export function shouldPrune(plan, options = {}) {
+  if (plan.remove.length === 0) return false;
+  if (options.prune) return true;
+  return PRUNE_POLICY === 'auto';
+}
+
+/**
+ * Print the removal plan, including its denominator. (XSPEC-384 R3)
+ *
+ * The counts are not decoration. A report that lists only the files it intends
+ * to touch is bit-for-bit identical to a report from a scan that only *saw*
+ * those files — which is the failure the previous code shipped for months,
+ * silently, because nothing ever printed how many files it had considered.
+ *
+ * @param {Object} plan - Result of planStandardsRemovals
+ * @param {boolean} provenanceWasEstablished - Whether ownership was already known
+ * @param {boolean} willDelete - Whether this run is going to act on the plan
+ */
+export function reportRemovalPlan(plan, provenanceWasEstablished, willDelete = false) {
+  if (plan.scanned === 0) return;
+
+  console.log();
+  console.log(chalk.gray(
+    `  .standards/ examined: ${plan.scanned} file(s) — ` +
+    `${plan.census.udsOwned} written by UDS, ` +
+    `${plan.census.foreign} not ours, ` +
+    `${plan.census.unknown} ownership unknown, ` +
+    `${plan.excluded.length} excluded`
+  ));
+  for (const { path: p, reason } of plan.excluded) {
+    console.log(chalk.gray(`    excluded ${p} (${reason})`));
+  }
+
+  if (!provenanceWasEstablished) {
+    console.log(chalk.gray(
+      '    first run with ownership tracking: files installed before this ' +
+      'release cannot be attributed yet, so none will be removed.'
+    ));
+  }
+
+  if (plan.remove.length === 0) {
+    if (plan.census.foreign > 0 || plan.census.unknown > 0) {
+      console.log(chalk.gray(
+        `    kept ${plan.census.foreign + plan.census.unknown} file(s) UDS did not write`
+      ));
+    }
+    return;
+  }
+
+  console.log();
+  console.log(chalk.yellow(
+    `  ${plan.remove.length} file(s) are no longer shipped by UDS` +
+    (willDelete ? ' and will be removed:' : ':')
+  ));
+  for (const { path: p, reason } of plan.remove) {
+    console.log(chalk.yellow(`    - ${p}  (${reason})`));
+  }
+  console.log(chalk.gray(
+    willDelete
+      ? '    Removing now (--prune). Files UDS did not write are never touched.'
+      : '    Not deleted. Re-run with --prune to remove them.'
+  ));
+}
 
 /**
  * Determine the correct target directory for a standard file.
@@ -170,7 +274,7 @@ function buildInstallCommand(pm, tag) {
  */
 async function updateCliAndExit(useBeta = false) {
   const msg = t().commands.update;
-  const spinner = ora(msg.updatingCli).start();
+  const spinner = createSpinner(msg.updatingCli).start();
 
   try {
     // Command is hardcoded - no user input, safe from injection
@@ -477,6 +581,23 @@ export async function updateCommand(options) {
     if (versionComparison > 0) {
       console.log(chalk.gray(`  ${msg.newerVersion.replace('{version}', currentVersion)}`));
     }
+
+    // Still forget records of files that are gone and no longer shipped. An
+    // adopter who followed MIGRATION-v6 §2 is on the current version by
+    // definition — telling them to run `uds update --prune` and then returning
+    // before anything is examined is how the complaint became unclearable.
+    const retiredOnLatest = pruneRetiredHashes(manifest, projectPath);
+    if (retiredOnLatest.length > 0) {
+      console.log();
+      console.log(chalk.gray(
+        `  ${(msg.droppedRetiredHashes || 'Dropped {count} manifest record(s) for files UDS no longer ships and that are already gone:').replace('{count}', retiredOnLatest.length)}`
+      ));
+      for (const path of retiredOnLatest) {
+        console.log(chalk.gray(`    - ${path}`));
+      }
+      writeManifest(manifest, projectPath);
+    }
+
     console.log();
     return;
   }
@@ -538,7 +659,7 @@ export async function updateCommand(options) {
 
   // Perform update
   console.log();
-  const spinner = ora(msg.updatingStandards).start();
+  const spinner = createSpinner(msg.updatingStandards).start();
 
   const results = {
     updated: [],
@@ -546,6 +667,21 @@ export async function updateCommand(options) {
     errors: []
   };
 
+  // Paths UDS actually wrote this run, taken from the copy result rather than
+  // recomputed from the source name. Recomputing is how `fileHashes` ended up
+  // with five `.standards/options/<name>.ai.yaml` entries for files that live
+  // at `.standards/options/<category>/<name>.ai.yaml`; a provenance record
+  // built the same way would claim files that do not exist and disown ones
+  // that do. (XSPEC-384 R1)
+  const writtenPaths = [];
+  const recordWritten = (result) => {
+    if (!result?.success || !result.data) return;
+    const abs = typeof result.data === 'string' ? result.data : null;
+    if (!abs) return;
+    const rel = relative(projectPath, abs).replace(/\\/g, '/');
+    if (rel && !rel.startsWith('..')) writtenPaths.push(rel);
+  };
+
   // Update standards
   const updateFormat = manifest.format || 'ai';
   const allStdsUpdate = getAllStandards();
@@ -561,6 +697,7 @@ export async function updateCommand(options) {
     const result = await copyStandard(sourcePath, getStandardTargetDir(sourcePath), projectPath);
     if (result.success) {
       results.updated.push(std);
+      recordWritten(result);
     } else {
       results.errors.push(`${std}: ${result.error}`);
     }
@@ -572,6 +709,7 @@ export async function updateCommand(options) {
     const result = await copyStandard(ext, '.standards', projectPath);
     if (result.success) {
       results.updated.push(ext);
+      recordWritten(result);
     } else {
       results.errors.push(`${ext}: ${result.error}`);
     }
@@ -593,7 +731,7 @@ export async function updateCommand(options) {
     }
 
     if (shouldInstallNew) {
-      const newSpinner = ora(msg.installingNewStandards).start();
+      const newSpinner = createSpinner(msg.installingNewStandards).start();
       let newCount = 0;
 
       for (const ns of newStandards) {
@@ -601,6 +739,7 @@ export async function updateCommand(options) {
         if (result.success) {
           manifest.standards.push(ns.source);
           results.updated.push(ns.source);
+          recordWritten(result);
           newCount++;
         } else {
           results.errors.push(`${ns.source}: ${result.error}`);
@@ -613,7 +752,7 @@ export async function updateCommand(options) {
 
   // Update integrations (unless --standards-only)
   if (!options.standardsOnly && manifest.integrations && manifest.integrations.length > 0) {
-    const intSpinner = ora(msg.syncingIntegrations).start();
+    const intSpinner = createSpinner(msg.syncingIntegrations).start();
 
     // Build installed standards list
     // Raw, not basename()d. Resolution needs the registry (an ID is not a
@@ -691,6 +830,7 @@ export async function updateCommand(options) {
             installedAt: new Date().toISOString()
           };
         }
+        refreshTrackedFileHash(manifest, projectPath, agentsMdResult.path);
       }
     }
 
@@ -751,6 +891,20 @@ export async function updateCommand(options) {
     manifest.fileHashes = {};
   }
 
+  // The set of `.standards/` files the *current* registry says should exist.
+  //
+  // Built by accumulating inside the loops that already resolve each entry,
+  // rather than by a second function that re-derives the same paths. A second
+  // derivation is a second copy, and the two would answer "where does this
+  // standard live" differently the moment either is edited — which is the
+  // failure mode XSPEC-384 is about, not a shape to reproduce. (XSPEC-384 R2)
+  const desiredStandardsFiles = new Set();
+
+  // Standards whose ID no longer resolves against the registry. Collected here
+  // instead of being silently `continue`d, because "skipped" and "deleted
+  // upstream" were previously indistinguishable — issue #165. (XSPEC-384 R2)
+  const unresolvedStandardIds = [];
+
   // Update hashes for standards (handles both ID format and legacy path format)
   const hashFormat = manifest.format || 'ai';
   const allStdsHash = getAllStandards();
@@ -759,7 +913,13 @@ export async function updateCommand(options) {
     let resolvedPath = std;
     if (!std.includes('/') && !std.includes('.')) {
       const entry = allStdsHash.find(r => r.id === std);
-      if (!entry) continue; // Skip unrecognized IDs (e.g. stale AI tool names)
+      if (!entry) {
+        // Unrecognized ID: either a standard removed from the registry, or a
+        // stale AI tool name an old CLI wrote into `standards`. Either way it
+        // is no longer a thing we ship, so it must not enter the desired set.
+        unresolvedStandardIds.push(std);
+        continue;
+      }
       const src = getStandardSource(entry, hashFormat);
       if (src) resolvedPath = src;
     }
@@ -767,6 +927,10 @@ export async function updateCommand(options) {
     const relativePath = (resolvedPath.includes('options/')
       ? join('.standards', 'options', fileName)
       : join('.standards', fileName)).replace(/\\/g, '/');
+    // Added before the hash check: a file that exists but failed to hash is
+    // still wanted. Nominating it for deletion because hashing failed would
+    // turn a transient read error into data loss.
+    desiredStandardsFiles.add(relativePath);
     const fullPath = join(projectPath, relativePath);
     const hashInfo = computeFileHash(fullPath);
     if (hashInfo) {
@@ -779,6 +943,7 @@ export async function updateCommand(options) {
     if (typeof ext !== 'string') continue;
     const fileName = basename(ext);
     const relativePath = join('.standards', fileName).replace(/\\/g, '/');
+    desiredStandardsFiles.add(relativePath);
     const fullPath = join(projectPath, relativePath);
     const hashInfo = computeFileHash(fullPath);
     if (hashInfo) {
@@ -795,21 +960,79 @@ export async function updateCommand(options) {
     }
   }
 
-  // Clean up orphan files in .standards/ that are no longer tracked
-  // This handles files renamed or removed between versions
-  const orphanFiles = scanForUntrackedFiles(projectPath, manifest);
-  const standardsOrphans = orphanFiles.filter(f => f.startsWith('.standards/'));
-  if (standardsOrphans.length > 0) {
-    for (const orphan of standardsOrphans) {
+  // Record what UDS wrote this run, then decide what (if anything) may go.
+  // (XSPEC-384 R1/R2/R3)
+  const provenanceWasEstablished = isProvenanceEstablished(manifest);
+  let provenanceCarrier = manifest;
+  for (const written of [...writtenPaths, ...results.integrations]) {
+    provenanceCarrier = recordFileProvenance(provenanceCarrier, written, 'update');
+  }
+  manifest.provenance = provenanceCarrier.provenance;
+
+  // Drop `standards` entries the registry no longer knows about. Previously
+  // these were `continue`d in three separate loops and left in the manifest
+  // forever, so `upstream.version` advanced to "latest" while the manifest
+  // still listed standards that had not existed for releases. (issue #165)
+  if (unresolvedStandardIds.length > 0) {
+    manifest.standards = manifest.standards.filter(s => !unresolvedStandardIds.includes(s));
+    console.log();
+    console.log(chalk.yellow(
+      `⚠ ${unresolvedStandardIds.length} manifest entr${unresolvedStandardIds.length === 1 ? 'y is' : 'ies are'} no longer in the registry and ${unresolvedStandardIds.length === 1 ? 'was' : 'were'} dropped:`
+    ));
+    for (const id of unresolvedStandardIds) {
+      console.log(chalk.gray(`    - ${id}`));
+    }
+  }
+
+  const removalPlan = planStandardsRemovals(projectPath, manifest, desiredStandardsFiles);
+  // Decide before reporting, so the report states what this run will actually
+  // do. Reporting first meant printing "Not deleted. Re-run with --prune" on a
+  // run that was about to delete — a message contradicting the very action it
+  // preceded, which is worse than no message.
+  const mayPrune = shouldPrune(removalPlan, options);
+  reportRemovalPlan(removalPlan, provenanceWasEstablished, mayPrune);
+
+  if (mayPrune && removalPlan.remove.length > 0) {
+    for (const { path: orphan } of removalPlan.remove) {
       try {
         unlinkSync(join(projectPath, orphan));
         results.updated.push(`removed: ${orphan}`);
+        delete manifest.fileHashes[orphan];
+        // Deleting the file is how we give up the claim on that path, so a
+        // file the user later creates under the same name is not inherited.
+        manifest.provenance = forgetFileProvenance(manifest, orphan).provenance;
       } catch {
         // Ignore removal errors
       }
     }
   }
 
+  // Records of files that are already gone and that UDS no longer ships. Not
+  // part of the removal plan above: that plan walks what is on disk, and these
+  // are precisely the ones that are not. Reported rather than done quietly,
+  // because a manifest shrinking without explanation is the shape this whole
+  // release is about.
+  const retiredHashes = pruneRetiredHashes(manifest, projectPath);
+  if (retiredHashes.length > 0) {
+    console.log();
+    console.log(chalk.gray(
+      `  ${(msg.droppedRetiredHashes || 'Dropped {count} manifest record(s) for files UDS no longer ships and that are already gone:').replace('{count}', retiredHashes.length)}`
+    ));
+    for (const path of retiredHashes) {
+      console.log(chalk.gray(`    - ${path}`));
+    }
+  }
+
+  // Provenance is only a complete account of what we own once a run has
+  // written the whole installed set. Until then every unrecorded file is
+  // `unknown` rather than `foreign`, and nothing gets deleted on the strength
+  // of an absent record. Establishing it here — after the writes, not before —
+  // is what makes the first upgrade conservative by construction rather than
+  // by a flag someone has to remember. (XSPEC-384 §4)
+  if (results.errors.length === 0) {
+    manifest.provenance = establishProvenance(manifest).provenance;
+  }
+
   // Migrate display_language: if manifest options is missing display_language,
   // attempt to backfill from ~/.udsrc ui.language so the project honours the
   // language the user already configured globally.
@@ -921,7 +1144,7 @@ export async function updateCommand(options) {
     }
 
     if (shouldRestore) {
-      const restoreSpinner = ora((msg.restoringMissing || 'Restoring missing files...')).start();
+      const restoreSpinner = createSpinner((msg.restoringMissing || 'Restoring missing files...')).start();
       const checkMsg = t().commands.check;
       let restoredCount = 0;
 
@@ -988,7 +1211,7 @@ export async function updateCommand(options) {
 
         // Install Skills if user agreed
         if (installSkills.length > 0) {
-          const skillSpinner = ora(msg.installingNewSkills || 'Installing Skills...').start();
+          const skillSpinner = createSpinner(msg.installingNewSkills || 'Installing Skills...').start();
           const skillsLocale = resolveLocale(manifest, projectPath, options);
           const skillResult = await installSkillsToMultipleAgents(installSkills, null, projectPath, skillsLocale);
 
@@ -1036,7 +1259,7 @@ export async function updateCommand(options) {
 
         // Update outdated Skills if user agreed
         if (updateSkills.length > 0) {
-          const updateSpinner = ora(msg.updatingSkills || 'Updating Skills...').start();
+          const updateSpinner = createSpinner(msg.updatingSkills || 'Updating Skills...').start();
           const updateLocale = resolveLocale(manifest, projectPath, options);
           const updateResult = await installSkillsToMultipleAgents(updateSkills, null, projectPath, updateLocale);
 
@@ -1074,7 +1297,7 @@ export async function updateCommand(options) {
 
         // Install Commands if user agreed
         if (installCommands.length > 0) {
-          const cmdSpinner = ora(msg.installingNewCommands || 'Installing commands...').start();
+          const cmdSpinner = createSpinner(msg.installingNewCommands || 'Installing commands...').start();
           const cmdLocale = resolveLocale(manifest, projectPath, options);
           const cmdResult = await installCommandsToMultipleAgents(installCommands, null, projectPath, cmdLocale);
 
@@ -1105,7 +1328,7 @@ export async function updateCommand(options) {
 
         // Update outdated Commands if user agreed
         if (updateCommands.length > 0) {
-          const updateCmdSpinner = ora(msg.updatingCommands || 'Updating Commands...').start();
+          const updateCmdSpinner = createSpinner(msg.updatingCommands || 'Updating Commands...').start();
           const updateCmdLocale = resolveLocale(manifest, projectPath, options);
           const updateCmdResult = await installCommandsToMultipleAgents(updateCommands, null, projectPath, updateCmdLocale);
 
@@ -1181,7 +1404,7 @@ export async function updateCommand(options) {
         let hasChanges = false;
 
         if (missingSkills.length > 0) {
-          const spinner = ora(msg.installingNewSkills || 'Installing Skills...').start();
+          const spinner = createSpinner(msg.installingNewSkills || 'Installing Skills...').start();
           const result = await installSkillsToMultipleAgents(missingSkills, null, projectPath, skillsLocale);
           if (!manifest.skills) manifest.skills = {};
           manifest.skills.installed = true;
@@ -1202,7 +1425,7 @@ export async function updateCommand(options) {
         }
 
         if (outdatedSkills.length > 0) {
-          const spinner = ora(msg.updatingSkills || 'Updating Skills...').start();
+          const spinner = createSpinner(msg.updatingSkills || 'Updating Skills...').start();
           const result = await installSkillsToMultipleAgents(outdatedSkills, null, projectPath, skillsLocale);
           if (!manifest.skills) manifest.skills = {};
           manifest.skills.version = repoInfo.skills.version;
@@ -1226,7 +1449,7 @@ export async function updateCommand(options) {
         }
 
         if (missingCommands.length > 0) {
-          const spinner = ora(msg.installingNewCommands || 'Installing commands...').start();
+          const spinner = createSpinner(msg.installingNewCommands || 'Installing commands...').start();
           const result = await installCommandsToMultipleAgents(missingCommands, null, projectPath, skillsLocale);
           if (!manifest.commands) manifest.commands = {};
           manifest.commands.installed = true;
@@ -1246,7 +1469,7 @@ export async function updateCommand(options) {
         }
 
         if (outdatedCommands.length > 0) {
-          const spinner = ora(msg.updatingCommands || 'Updating Commands...').start();
+          const spinner = createSpinner(msg.updatingCommands || 'Updating Commands...').start();
           const result = await installCommandsToMultipleAgents(outdatedCommands, null, projectPath, skillsLocale);
           if (!manifest.commands) manifest.commands = {};
           manifest.commands.version = repoInfo.skills.version;
@@ -1366,11 +1589,58 @@ export async function updateCommand(options) {
 
   console.log();
 
+  // 錯誤訊息單一出口閘門：問過才寫，而且從不覆寫。
+  await offerErrorExitGate(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);
 }
 
+/**
+ * 提供錯誤訊息單一出口閘門——**顯示它是什麼、問過、才寫，而且絕不覆寫既有檔案。**
+ *
+ * 🔴 為什麼不自動寫：`uds` 是別人裝進自己 repo 的工具。未經同意往陌生人的專案
+ *    寫一支可執行腳本，比它要修的那個問題更糟——那會變成信任問題，而不是 bug。
+ *    採用者說不要，我們就不寫，而且下次 `uds check` 只會再提一次，不會偷偷放進去。
+ *
+ * ⚠️ 已存在就直接跳過，連問都不問：那個檔案裡的 CONFIG 是採用者自己填的，
+ *    我們沒有立場拿範本蓋掉它。要更新內容是另一件事，不在這裡做。
+ */
+async function offerErrorExitGate(projectPath, options) {
+  const dest = join(projectPath, 'scripts', 'check-error-exit.mjs');
+  if (existsSync(dest)) return;                              // 他們自己的檔案
+  if (!existsSync(join(projectPath, 'src'))) return;         // 沒有原始碼就沒有這個問題
+
+  const src = join(getRepoRoot(), 'templates', 'gates', 'check-error-exit.mjs');
+  if (!existsSync(src)) return;                              // 範本沒出貨——沉默，不要假裝提供了
+
+  console.log(chalk.bold('  錯誤訊息單一出口閘門'));
+  console.log(chalk.gray('    防的是：每個呼叫端各自把錯誤回應拼成給人看的字串。'));
+  console.log(chalk.gray('    第一處是實作，第二處開始就會各寫各的，而畫面上只剩一句 Bad Request。'));
+  console.log(chalk.gray(`    要寫入：scripts/check-error-exit.mjs（純 Node、零相依、${Math.round(readFileSync(src, 'utf-8').length / 1024)}KB）`));
+  console.log(chalk.gray('    寫入後它會 exit 2 直到你填好 CONFIG——那是刻意的，'));
+  console.log(chalk.gray('    一支在新 repo 裡靜靜回綠的閘門跟一支沒裝的無從分辨。'));
+  console.log();
+
+  const ok = await confirmOrFail({
+    message: '要把這道閘門寫進 scripts/check-error-exit.mjs 嗎？',
+    defaultValue: false,   // 🔴 預設不寫。沉默不是同意。
+    options
+  });
+  if (!ok) {
+    console.log(chalk.gray('  跳過。`uds check` 之後會再提醒，但不會自己寫進去。'));
+    console.log();
+    return;
+  }
+
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, readFileSync(src, 'utf-8'), 'utf-8');
+  console.log(chalk.green('  ✓ 已寫入 scripts/check-error-exit.mjs'));
+  console.log(chalk.gray('    下一步：填好檔頭的 CONFIG，然後把它接進你的 CI 或 pre-commit。'));
+  console.log();
+}
+
 /**
  * Regenerate integration files for all configured AI tools
  * Reusable core logic that can be called from both updateIntegrationsOnly and configureCommand
@@ -1452,6 +1722,7 @@ export function regenerateIntegrations(projectPath, manifest) {
           installedAt: now
         };
       }
+      refreshTrackedFileHash(manifest, projectPath, agentsMdResult.path);
     }
   }
 
@@ -1575,7 +1846,7 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
     return;
   }
 
-  const spinner = ora(msg.regeneratingIntegrations).start();
+  const spinner = createSpinner(msg.regeneratingIntegrations).start();
 
   // Use reusable regeneration function
   const results = regenerateIntegrations(projectPath, manifest);
@@ -1604,6 +1875,188 @@ async function updateIntegrationsOnly(projectPath, manifest, options = {}) {
   process.exit(0);
 }
 
+/**
+ * Rebuild `manifest.integrationConfigs` from what the manifest already records.
+ *
+ * 🔴 Only `uds init`'s interactive flow and `--sync-refs` itself ever wrote this
+ * key; no update or reconcile path backfills it, so a project created with
+ * `uds init -y` carries `{}` from the first day (reproduced on a clean 6.9.0
+ * project, 2026-09-16). `--sync-refs` then refuses to run — and `uds check` was
+ * recommending exactly that command. Everything the config holds is derivable
+ * from the manifest, so derive it instead of demanding the user re-init.
+ *
+ * Existing entries are never overwritten: they may hold choices (categories,
+ * content mode) that this derivation cannot know.
+ *
+ * @param {Object} manifest - Manifest object (mutated)
+ * @returns {number} How many entries were added
+ */
+export function backfillIntegrationConfigs(manifest) {
+  if (!manifest.integrationConfigs) manifest.integrationConfigs = {};
+
+  const tools = manifest.aiTools?.length ? manifest.aiTools : [];
+  const byFile = new Map();
+  for (const tool of tools) {
+    const file = resolveIntegrationFile(tool) || getToolFilePath(tool);
+    if (file && !byFile.has(file)) byFile.set(file, tool);
+  }
+  // Integrations can be recorded as file names (`CLAUDE.md`) or tool keys.
+  for (const entry of manifest.integrations || []) {
+    const file = resolveIntegrationFile(entry) || (String(entry).includes('.') ? String(entry) : null);
+    if (!file) continue;
+    if (!byFile.has(file)) {
+      const tool = getToolFromPath(file) || resolveToolKeyFromEntry(entry);
+      if (tool) byFile.set(file, tool);
+    }
+  }
+
+  let added = 0;
+  for (const [file, tool] of byFile) {
+    if (manifest.integrationConfigs[file]) continue;
+    manifest.integrationConfigs[file] = {
+      ...buildToolIntegrationConfig(manifest, tool),
+      format: manifest.format || 'ai',
+      backfilledAt: new Date().toISOString()
+    };
+    added++;
+  }
+  return added;
+}
+
+function resolveToolKeyFromEntry(entry) {
+  const key = String(entry).replace(/\.[^.]+$/, '').toLowerCase();
+  return SUPPORTED_AI_TOOLS?.[key] ? key : null;
+}
+
+/**
+ * If the manifest already tracks this file, make its record describe what is on
+ * disk now.
+ *
+ * Every path that writes AGENTS.md recorded `integrationBlockHashes` and none
+ * recorded `fileHashes`, so a project whose manifest tracked the file (an older
+ * install, or one where AGENTS.md was written as a tool's integration file) got
+ * `⚠ AGENTS.md (modified)` from `uds check` the moment UDS itself regenerated
+ * it. UDS wrote the file and did not record what it wrote.
+ *
+ * Conditional on purpose. `uds init` does not enrol AGENTS.md in `fileHashes`,
+ * and adopters are expected to extend that summary — a path that started
+ * tracking it would convert every legitimate edit into a reported fault. This
+ * only ever refreshes a record that already exists.
+ *
+ * @param {Object} manifest - Project manifest (mutated)
+ * @param {string} projectPath - Project root
+ * @param {string} relativePath - Path as UDS reports it
+ * @returns {boolean} Whether a record was refreshed
+ */
+export function refreshTrackedFileHash(manifest, projectPath, relativePath) {
+  if (!manifest?.fileHashes || !relativePath) return false;
+  const normalized = String(relativePath).replace(/\\/g, '/');
+  if (!(normalized in manifest.fileHashes)) return false;
+
+  const hashInfo = computeFileHash(join(projectPath, normalized));
+  if (!hashInfo) return false;
+
+  manifest.fileHashes[normalized] = { ...hashInfo, installedAt: new Date().toISOString() };
+  return true;
+}
+
+/**
+ * Forget `fileHashes` records for files that are gone AND that UDS no longer
+ * ships.
+ *
+ * `--prune` deletes files it finds while walking `.standards/`. A file the
+ * adopter already removed by hand is not in that walk, so its record survived
+ * every prune — and the record is what made `uds check` report the completed
+ * migration as seven faults. Following MIGRATION-v6 §2 therefore produced a
+ * complaint that no command could clear.
+ *
+ * This is not a deletion. The file is already absent and no registry entry can
+ * ever resolve to it again, so the record cannot refer to anything. Both facts
+ * are required: a missing file UDS still ships is a real fault and stays; a
+ * descoped standard still on disk is `--prune`'s business, gated on ownership,
+ * and is left alone here.
+ *
+ * @param {Object} manifest - Project manifest (mutated)
+ * @param {string} projectPath - Project root
+ * @param {{shippable?: Set<string>}} [deps] - Injection point for tests
+ * @returns {string[]} Paths whose records were dropped, sorted
+ */
+export function pruneRetiredHashes(manifest, projectPath, deps = {}) {
+  if (!manifest?.fileHashes) return [];
+
+  let shippable;
+  try {
+    shippable = deps.shippable || getShippableFilenames();
+  } catch {
+    return [];
+  }
+
+  // A shippable set this small means the registry did not load, not that UDS
+  // stopped shipping everything. Without this arm a broken install would empty
+  // the manifest and every downstream check would go quiet at the same time.
+  if (!shippable || shippable.size < 50) return [];
+
+  const dropped = [];
+  for (const recorded of Object.keys(manifest.fileHashes)) {
+    const normalized = recorded.replace(/\\/g, '/');
+    if (!normalized.startsWith('.standards/')) continue;
+    const fileName = normalized.split('/').pop();
+    if (shippable.has(fileName)) continue;
+    if (existsSync(join(projectPath, recorded))) continue;
+    delete manifest.fileHashes[recorded];
+    dropped.push(recorded);
+  }
+  return dropped.sort();
+}
+
+/**
+ * Build the config `--sync-refs` regenerates an integration file from.
+ *
+ * The stored `integrationConfigs[file]` is a snapshot taken when the file was
+ * installed. Its `categories` are the thing sync-refs exists to update, and its
+ * `installedStandards` is the thing that must never be trusted: it is not
+ * refreshed by any path, so on a project upgraded across majors it still lists
+ * standards that stopped shipping, and whatever it lists becomes the file's
+ * content. That is how a manifest holding 73 standards produced a CLAUDE.md
+ * announcing 76, which `uds check` then flagged against the same manifest.
+ *
+ * So: manifest-derived fields win, the caller's freshly computed categories win
+ * over both, and anything the manifest knows nothing about (timestamps, fields
+ * a future version adds) is carried through untouched.
+ *
+ * `outputLanguage` is the one place the stored value still gets a say — a
+ * manifest with no `output_language` should not silently reset a project that
+ * chose one before the option was recorded there.
+ *
+ * @param {Object} manifest - Project manifest
+ * @param {string} toolName - Tool key (e.g. 'claude-code')
+ * @param {Object} storedConfig - The existing integrationConfigs entry
+ * @param {string[]} expectedCategories - Categories computed from current standards
+ * @returns {Object} Config for writeIntegrationFile
+ */
+export function refreshIntegrationConfig(manifest, toolName, storedConfig = {}, expectedCategories = []) {
+  const outputLanguage =
+    manifest.options?.output_language
+    || manifest.options?.commit_language
+    || storedConfig.outputLanguage
+    || storedConfig.commitLanguage
+    || 'english';
+
+  const fresh = buildToolIntegrationConfig(
+    { ...manifest, options: { ...(manifest.options || {}), output_language: outputLanguage } },
+    toolName
+  );
+
+  return {
+    ...storedConfig,
+    ...fresh,
+    tool: toolName,
+    categories: expectedCategories,
+    outputLanguage,
+    format: manifest.format || storedConfig.format || 'ai'
+  };
+}
+
 /**
  * Sync integration file references based on manifest standards
  * @param {string} projectPath - Project path
@@ -1615,6 +2068,16 @@ async function syncIntegrationReferences(projectPath, manifest, { plan = false }
   console.log(chalk.cyan(msg.syncingRefs));
   console.log();
 
+  // Rebuild the config when it is absent rather than sending the user away —
+  // the manifest holds everything it is derived from.
+  if (!manifest.integrationConfigs || Object.keys(manifest.integrationConfigs).length === 0) {
+    const filled = backfillIntegrationConfigs(manifest);
+    if (filled > 0) {
+      console.log(chalk.gray(`  ${(msg.integrationConfigsBackfilled || 'Rebuilt integration config for {count} file(s) from the manifest.').replace('{count}', filled)}`));
+      console.log();
+    }
+  }
+
   // Check if integrationConfigs exists
   if (!manifest.integrationConfigs || Object.keys(manifest.integrationConfigs).length === 0) {
     console.log(chalk.yellow(msg.noIntegrationConfigs));
@@ -1667,14 +2130,9 @@ async function syncIntegrationReferences(projectPath, manifest, { plan = false }
       continue;
     }
 
-    // Regenerate the integration file with updated categories
-    const newConfig = {
-      ...config,
-      tool: toolName,
-      categories: expectedCategories,
-      // Pass output_language for dynamic commit standards generation
-      outputLanguage: manifest.options?.output_language || manifest.options?.commit_language || config.outputLanguage || config.commitLanguage || 'english'
-    };
+    // Regenerate the integration file with updated categories, from the
+    // manifest rather than from the snapshot stored beside it.
+    const newConfig = refreshIntegrationConfig(manifest, toolName, config, expectedCategories);
 
     if (plan) {
       console.log(chalk.yellow(`  ~ ${integrationPath}: categories would change to ${expectedCategories.join(', ') || '(none)'} (dry run — nothing is written)`));
@@ -1845,7 +2303,35 @@ async function updateSkillsOnly(projectPath, manifest, options) {
       // Convert legacy format to new format
       const legacyLocation = manifest.skills.location;
       if (legacyLocation === 'user' || legacyLocation === 'project') {
-        skillsInstallations.push({ agent: 'claude-code', level: legacyLocation });
+        // 🔴 A legacy manifest records a LOCATION, never a tool — and this used to
+        // fill the gap with `claude-code`, unconditionally. For everyone who ran the
+        // old `uds init -y` in a codex or opencode repo, that guess is wrong and
+        // self-perpetuating: the fix to `init.js` would never reach them, because
+        // update would keep re-installing to `.claude/skills/` on the strength of a
+        // tool name nobody ever recorded. (XSPEC-408 §18.3 — Codex does not read
+        // that directory; measured, two arms, 2026-09-08.)
+        //
+        // So re-derive from what is actually detected in the repo, and keep
+        // `claude-code` only as the fallback for when nothing is detected — which is
+        // exactly the case the old line was written for.
+        let detected = {};
+        try {
+          detected = detectAITools(projectPath) || {};
+        } catch {
+          // Detection failing puts us in the "we do not know" case, which is exactly
+          // what the old unconditional `claude-code` line was for. Never let a probe
+          // for extra information break the update that would have worked without it.
+          detected = {};
+        }
+        const detectedSkillsTools = Object.entries(detected)
+          .filter(([, present]) => present)
+          .map(([key]) => (key === 'claudeCode' ? 'claude-code' : key === 'geminiCli' ? 'gemini-cli' : key))
+          .filter(agent => {
+            const config = getAgentConfig(agent);
+            return Boolean(config?.supportsSkills && config?.skills);
+          });
+        const agents = detectedSkillsTools.length > 0 ? detectedSkillsTools : ['claude-code'];
+        for (const agent of agents) skillsInstallations.push({ agent, level: legacyLocation });
       } else if (legacyLocation === 'marketplace') {
         console.log(chalk.yellow(msg.skillsViaMarketplace || 'Skills installed via Marketplace'));
         console.log(chalk.gray(`  ${msg.updateViaMarketplace || 'Update through Plugin Marketplace'}`));
@@ -1895,7 +2381,7 @@ async function updateSkillsOnly(projectPath, manifest, options) {
     return;
   }
 
-  const spinner = ora(msg.installingSkills || 'Installing Skills...').start();
+  const spinner = createSpinner(msg.installingSkills || 'Installing Skills...').start();
 
   const skillsLocaleForUpdate = resolveLocale(manifest, projectPath, options);
   const result = await installSkillsToMultipleAgents(
@@ -1913,8 +2399,16 @@ async function updateSkillsOnly(projectPath, manifest, options) {
   }).join(', ');
 
   if (result.totalErrors === 0) {
+    // 🔴 `{count}` is worded "AI tools" in every locale, and this passed
+    // `totalInstalled` — the number of skill FILES written, summed across targets.
+    // A two-tool update of 55 skills printed "Updated Skills for 165 AI tools".
+    // It was invisible while this branch only ran from the interactive flow; the
+    // fix to `init.js` makes it the common path, so it stops being invisible.
     spinner.succeed((msg.skillsUpdated || 'Updated Skills in {count} locations: {locations}')
-      .replace('{count}', result.totalInstalled)
+      // Counted from the same list that builds `locations`, so the number and the
+      // names can never disagree — and it does not depend on the shape of the
+      // installer's return value.
+      .replace('{count}', fileBasedInstallations.length)
       .replace('{locations}', locations));
   } else {
     spinner.warn((msg.skillsUpdatedWithErrors || 'Updated Skills with {errors} errors')
@@ -2011,7 +2505,7 @@ async function updateCommandsOnly(projectPath, manifest, options) {
   }
   console.log();
 
-  const spinner = ora(msg.installingCommands || 'Installing commands...').start();
+  const spinner = createSpinner(msg.installingCommands || 'Installing commands...').start();
 
   const commandsLocale = resolveLocale(manifest, projectPath, options);
   const result = await installCommandsToMultipleAgents(
@@ -2508,7 +3002,7 @@ async function handleRollback(projectPath) {
  * Handle --plan: show what the reconciler would do without executing.
  */
 async function handlePlan(projectPath, options) {
-  const spinner = ora('Calculating reconciliation plan...').start();
+  const spinner = createSpinner('Calculating reconciliation plan...').start();
 
   const result = await reconcilerPlan(projectPath, { force: false });
 
@@ -2583,7 +3077,7 @@ async function handleReconcile(projectPath, options, { force }) {
   }
 
   // Execute
-  const spinner = ora('Applying reconciliation plan...').start();
+  const spinner = createSpinner('Applying reconciliation plan...').start();
 
   const result = await reconcile(projectPath, {
     force,