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

package/src/commands/update.js

@@ -4,7 +4,7 @@ import { select, confirm as inquirerConfirm, checkbox, Separator } from '@inquir
 import { execSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
 import { join, basename, dirname, relative } from 'path';
-import { readManifest, writeManifest, copyStandard, isInitialized, getRepoRoot } from '../utils/copier.js';
+import { readManifest, writeManifest, copyStandard, copyExtension, isInitialized, getRepoRoot } from '../utils/copier.js';
 import { getRepositoryInfo, getAllStandards, getShippableFilenames, getStandardSource } from '../utils/registry.js';
 import { computeFileHash, planStandardsRemovals, refreshIntegrationBlockHashes, pruneIntegrationFileHashes } from '../utils/hasher.js';
 import { AmbiguousMarkerError } from '../utils/marker-locator.js';
@@ -47,6 +47,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 { migrateLegacyHuskyHook } from '../utils/legacy-hook-migration.js';
 import {
   promptSkillsInstallLocation,
   promptCommandsInstallation
@@ -498,6 +500,13 @@ export async function updateCommand(options) {
   const scopedToSkills = !!options.skills;
   const scopedToCommands = !!options.commands;
 
+  // A pre-commit line an older UDS wrote asks npm for the bare name `uds`, which
+  // is not this project. Fixed here, before any mode below can return early
+  // (an up-to-date adopter still has it). Narrowed runs stay narrowed.
+  if (!options.rollback && !scopedToSkills && !scopedToCommands && !options.standardsOnly) {
+    migrateLegacyPreCommitHook(projectPath, manifest, { plan: !!options.plan });
+  }
+
   // Handle --rollback option (DSR). It restores a whole backup, so a scope
   // flag cannot narrow it — say so rather than appearing to honour it.
   if (options.rollback) {
@@ -729,7 +738,8 @@ export async function updateCommand(options) {
   // Update extensions (skip non-string entries like custom-domain objects)
   for (const ext of manifest.extensions) {
     if (typeof ext !== 'string') continue;
-    const result = await copyStandard(ext, '.standards', projectPath);
+    // Package-only: an extension is never downloaded (XSPEC-452 R2).
+    const result = await copyExtension(ext, '.standards', projectPath);
     if (result.success) {
       results.updated.push(ext);
       recordWritten(result);
@@ -1837,6 +1847,47 @@ async function switchClaudeTarget(projectPath, manifest, target, options) { // e
  * @param {Object} manifest - Manifest object (will be mutated with updated hashes)
  * @returns {{success: boolean, updated: string[], errors: string[]}}
  */
+/**
+ * Swap the pre-commit line an older UDS wrote (`npx` + the bare name `uds`) for
+ * the block current UDS writes, and say what was done or why not.
+ *
+ * Runs in every `uds update` mode that is not narrowed to something else, and in
+ * `--with-hooks`, and it runs BEFORE the "already up to date" early return: an
+ * adopter whose standards are current is exactly the one still carrying the old
+ * line. Under `--plan` it reports and writes nothing.
+ *
+ * Only a line UDS can be shown to have written is changed (exact match under
+ * UDS's marker comment — see legacy-hook-migration.js); any other bare-name line
+ * is reported with its line number and left alone.
+ *
+ * @param {string} projectPath
+ * @param {object} manifest - mutated only to carry a refreshed install record
+ * @param {{plan?: boolean}} [opts]
+ * @returns {ReturnType<typeof migrateLegacyHuskyHook>}
+ */
+export function migrateLegacyPreCommitHook(projectPath, manifest, { plan = false } = {}) {
+  const msg = t().commands.update;
+  const r = migrateLegacyHuskyHook(projectPath, { plan, manifest });
+  if (r.state === 'error') {
+    console.log(chalk.yellow(`  ${msg.hookMigrateFailed.replace('{error}', r.error)}`));
+    console.log();
+    return r;
+  }
+  if (r.state === 'migrated') console.log(chalk.green(`  ${msg.hookMigrated}`));
+  if (r.state === 'would-migrate') console.log(chalk.cyan(`  ${msg.hookWouldMigrate}`));
+  for (const k of r.kept) {
+    console.log(chalk.yellow(`  ${msg.hookLegacyKept.replace('{line}', k.line).replace('{text}', k.text)}`));
+  }
+  if (r.state !== 'none') console.log();
+  if (r.recorder) {
+    persistRecorder(projectPath, r.recorder);
+    // The manifest object is written again later in most update paths; without
+    // this the record persisted just above would be overwritten by the older copy.
+    Object.assign(manifest, mergeRecorderInto(manifest, r.recorder));
+  }
+  return r;
+}
+
 /**
  * `uds update --with-hooks [--ai-tool <list>] [--plan] [--force]`
  *
@@ -1858,6 +1909,9 @@ export async function updateHooksOnly(projectPath, manifest, options = {}) {
     console.log();
   }
 
+  // The hook lines UDS wrote in the past belong to this command's subject too.
+  migrateLegacyPreCommitHook(projectPath, manifest, { plan: !!options.plan });
+
   const capable = HOOK_CAPABLE_TOOLS.join(', ');
   const resolved = resolveHookTools(projectPath, manifest, { aiTool: options.aiTool });
 
@@ -1887,11 +1941,16 @@ export async function updateHooksOnly(projectPath, manifest, options = {}) {
     console.log(chalk.gray(`  ${tool}: ${resolved.sources[tool].join(', ')}`));
   }
 
-  const { results, scripts } = installMissingHooks(projectPath, resolved.tools, {
+  const { results, scripts, artifacts } = installMissingHooks(projectPath, resolved.tools, {
     plan: !!options.plan,
     overwriteScripts: !!options.force,
   });
 
+  // Record what was just written (hook scripts, and folders UDS had to create) in
+  // the manifest, so `uds uninstall` can remove exactly that. Never on --plan: a
+  // plan writes nothing, and the recorder is empty then anyway.
+  if (!options.plan) persistRecorder(projectPath, artifacts);
+
   let failed = false;
   for (const r of results) {
     const rel = r.path ? relative(projectPath, r.path) || r.path : '';

package/src/core/install-records.js

@@ -0,0 +1,191 @@
+/**
+ * Install records — the manifest's account of what UDS itself put on disk, kept
+ * so that `uds uninstall` removes exactly that and nothing else.
+ *
+ * Why a record and not a rule: `uds uninstall` used to leave four kinds of UDS
+ * output behind (hook scripts under scripts/hooks/, emptied `.codex/`-style
+ * folders, integration files whose generated header sits outside the UDS
+ * marker block, and the body of the native pre-commit hook). Each could be
+ * cleaned by pattern-matching on its content or path — and each of those
+ * patterns also matches files an adopter wrote themselves (`scripts/hooks/` is
+ * a directory UDS scaffolds INSIDE the adopter's project, where their own hook
+ * scripts may live). Origin is a fact about the moment of writing, so it is
+ * recorded then: a file is deleted only if a record says UDS wrote it AND its
+ * content still hashes to what UDS wrote. No record, or a changed hash, means
+ * the file is kept and the reason is printed.
+ *
+ * Deliberately NOT stored in `fileHashes` (`uds check` treats that as the list of
+ * standards files and would report these as modified/untracked) or in
+ * `provenance` (`uds update` prunes entries outside its expected set).
+ * `installedArtifacts` is read by nothing except uninstall.
+ *
+ * Shape:
+ *   installedArtifacts: {
+ *     files: { '<rel/path>': { kind, hash, size, installedAt } },
+ *     createdDirs: ['<rel/dir>', ...]          // directories UDS had to mkdir
+ *   }
+ *
+ * `kind` selects what `hash` covers:
+ *   'hook-script', 'git-hook'  → whole file (line endings normalized)
+ *   'integration-file'         → everything outside the UDS marker block
+ *
+ * @module core/install-records
+ */
+
+import { existsSync, mkdirSync, lstatSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname, relative, isAbsolute } from 'path';
+import { computeFileHash, computeOutsideBlockHash } from '../utils/hasher.js';
+import { getManifestPath } from './manifest.js';
+
+export const RECORDS_KEY = 'installedArtifacts';
+
+export const RECORD_KINDS = Object.freeze({
+  HOOK_SCRIPT: 'hook-script',
+  GIT_HOOK: 'git-hook',
+  INTEGRATION_FILE: 'integration-file'
+});
+
+const norm = (p) => String(p).replace(/\\/g, '/');
+
+/** A fresh, empty recorder. Installers fill it; a caller persists it. */
+export function newRecorder() {
+  return { files: {}, createdDirs: [] };
+}
+
+/**
+ * The hash a record of this kind holds for a file as it is on disk right now.
+ * Also what uninstall recomputes and compares — one function, so the two sides
+ * cannot drift apart.
+ * @returns {{hash: string, size: number}|null}
+ */
+export function currentHashFor(kind, absPath) {
+  if (kind === RECORD_KINDS.INTEGRATION_FILE) return computeOutsideBlockHash(absPath);
+  return computeFileHash(absPath);
+}
+
+/**
+ * Record a file UDS has just written. Call it AFTER the write, so the hash is of
+ * what is on disk. No-op (returns false) if the file cannot be hashed.
+ */
+export function recordFile(recorder, projectPath, relPath, kind) {
+  const rel = norm(relPath);
+  const h = currentHashFor(kind, join(projectPath, rel));
+  if (!h) return false;
+  recorder.files[rel] = { kind, hash: h.hash, size: h.size, installedAt: new Date().toISOString() };
+  return true;
+}
+
+/**
+ * `mkdir -p`, remembering every directory that did not exist before this call.
+ * "UDS created this directory" is only knowable at the moment of creation; after
+ * that an empty `.codex/` looks the same whether UDS or the adopter made it.
+ */
+export function mkdirTracked(recorder, projectPath, absDir) {
+  const missing = [];
+  let cur = absDir;
+  while (!existsSync(cur)) {
+    missing.push(cur);
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  if (missing.length === 0) return;
+  mkdirSync(absDir, { recursive: true });
+  for (const dir of missing.reverse()) {
+    const rel = norm(relative(projectPath, dir));
+    if (!rel || rel.startsWith('..') || isAbsolute(rel)) continue;
+    if (!recorder.createdDirs.includes(rel)) recorder.createdDirs.push(rel);
+  }
+}
+
+/** Fold a recorder into a manifest object (returned as a new object; input untouched). */
+export function mergeRecorderInto(manifest, recorder) {
+  const prev = manifest?.[RECORDS_KEY] || {};
+  const dirs = new Set([...(prev.createdDirs || []), ...(recorder?.createdDirs || [])]);
+  return {
+    ...manifest,
+    [RECORDS_KEY]: {
+      files: { ...(prev.files || {}), ...(recorder?.files || {}) },
+      createdDirs: [...dirs]
+    }
+  };
+}
+
+/** Drop records for paths UDS has now removed. */
+export function forgetRecords(manifest, relPaths) {
+  const prev = manifest?.[RECORDS_KEY];
+  if (!prev) return manifest;
+  const gone = new Set((relPaths || []).map(norm));
+  const files = Object.fromEntries(Object.entries(prev.files || {}).filter(([k]) => !gone.has(k)));
+  const createdDirs = (prev.createdDirs || []).filter((d) => !gone.has(d));
+  return { ...manifest, [RECORDS_KEY]: { files, createdDirs } };
+}
+
+/** The record for a path, or undefined. */
+export function getFileRecord(manifest, relPath) {
+  return manifest?.[RECORDS_KEY]?.files?.[norm(relPath)];
+}
+
+/** True when the recorder holds anything worth writing. */
+export function hasRecords(recorder) {
+  return !!recorder && (Object.keys(recorder.files).length > 0 || recorder.createdDirs.length > 0);
+}
+
+/**
+ * Persist a recorder into the project's manifest on disk. For callers that run
+ * after the manifest was written (init's hook step, `uds update --with-hooks`).
+ * Returns false — and writes nothing — when there is nothing to record or no
+ * manifest to record it in.
+ *
+ * Reads and writes the manifest as RAW JSON, not through `readManifest`. That
+ * function migrates on read (it rewrites `standards` from paths to registry IDs,
+ * among other normalizations), so a read-modify-write through it would silently
+ * change every other field in the file as a side effect of recording one new
+ * one — measured: the e2e test "auto-restore missing files" reads `standards`
+ * straight from the file `uds init` wrote and started failing because init's
+ * manifest had come out in a different format.
+ */
+export function persistRecorder(projectPath, recorder) {
+  if (!hasRecords(recorder)) return false;
+  const manifestPath = getManifestPath(projectPath);
+  if (!existsSync(manifestPath)) return false;
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return false;
+  }
+  if (!raw || typeof raw !== 'object') return false;
+  writeFileSync(manifestPath, JSON.stringify(mergeRecorderInto(raw, recorder), null, 2));
+  return true;
+}
+
+/** Is `absPath` a real directory (not a symlink to one)? Uninstall never follows links. */
+export function isRealDirectory(absPath) {
+  try {
+    const st = lstatSync(absPath);
+    return st.isDirectory() && !st.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @returns {{ state: 'proven'|'no-record'|'changed', why: string }}
+ *   proven     a record exists and the file still hashes to it
+ *   no-record  nothing says UDS wrote it (older UDS, or written by hand)
+ *   changed    UDS wrote it, and it has been edited since
+ */
+export function proveUnchanged(manifest, projectPath, relPath) {
+  const rec = getFileRecord(manifest, relPath);
+  if (!rec) {
+    return {
+      state: 'no-record',
+      why: 'no install record — installed by an older UDS or not by UDS, so UDS cannot prove it wrote this'
+    };
+  }
+  const now = currentHashFor(rec.kind, join(projectPath, relPath));
+  if (now && now.hash === rec.hash) return { state: 'proven', why: 'unchanged since UDS wrote it' };
+  return { state: 'changed', why: 'modified since UDS wrote it' };
+}
+

package/src/i18n/messages.js

@@ -875,7 +875,7 @@ export const messages = {
         // Pre-commit hook wiring (XSPEC: uds init writes a hook but never
         // confirmed git would run it — this reports the gap, read-only)
         hookNotWiredTitle: '⚠ [pre-commit] {file} was installed, but git will not run it.',
-        hookNotWiredOverride: '  git core.hooksPath is set to "{path}" — UDS will not override it. Confirm the hook there also runs `npx uds check`, or switch it yourself: git config --local core.hooksPath .husky',
+        hookNotWiredOverride: '  git core.hooksPath is set to "{path}" — UDS will not override it. Confirm the hook there also runs `universal-dev-standards check` (the installed CLI — not the short name "uds", which on the npm registry is an unrelated package), or switch it yourself: git config --local core.hooksPath .husky',
         hookNotWiredUnwired: '  git core.hooksPath is not set, and {file} is not on git\'s default hook path.',
         hookNotWiredFix: '  Fix (per-clone — not committed, teammates must repeat it): git config --local core.hooksPath .husky',
         hookNotWiredFixNative: '  Fix: point core.hooksPath back to the default (git config --local --unset core.hooksPath), or add `uds check` under "{path}" instead.',
@@ -892,6 +892,8 @@ export const messages = {
         // file or directory". Measured 2026-09-27 in CI (windows-latest).
         hookMissingShebangTitle: '⚠ [pre-commit] {file} has no shebang line — git cannot run it on Windows.',
         hookMissingShebangFix: '  Fix: add a `#!/bin/sh` shebang as the very first line of {file} (a husky-managed hook gets this automatically the next time `uds init` touches it), or re-run `uds init`.',
+        hookBareUdsTitle: '⚠ [pre-commit] {file} asks npm to run the bare name "uds", which on the npm registry is an unrelated package (not this project).',
+        hookBareUdsFix: '  Fix: run `uds update` — it replaces the line UDS itself wrote with one that only runs the installed UDS CLI. A line you wrote or edited yourself is left alone; change it to `universal-dev-standards check`.',
         // Summary mode (--summary)
         summary_mode: {
           title: 'UDS Status Summary',
@@ -1038,6 +1040,11 @@ export const messages = {
         currentVersion: 'Current version',
         latestVersion: 'Latest version',
         upToDate: '✓ Standards are up to date.',
+        // Pre-commit hook migration (bare-name `uds` on the npm registry is not this project)
+        hookMigrated: '✓ .husky/pre-commit: replaced the line an older UDS wrote (it asked npm to resolve the bare name "uds", which is not this project) with one that runs only the installed UDS CLI.',
+        hookWouldMigrate: '+ .husky/pre-commit: would replace the line an older UDS wrote (it asks npm to resolve the bare name "uds", which is not this project) with one that runs only the installed UDS CLI.',
+        hookLegacyKept: '⚠ .husky/pre-commit line {line} ("{text}") asks npm to resolve the bare name "uds", which on the npm registry is an unrelated package. UDS did not write this exact line, so it was left alone. Change it to "universal-dev-standards check" — it needs the UDS CLI installed in this project or on PATH.',
+        hookMigrateFailed: '⚠ Could not rewrite .husky/pre-commit: {error}. The line that asks npm for the bare name "uds" is still there — change it to "universal-dev-standards check".',
         newerVersion: '(You have a newer version than the registry: {version})',
         updateAvailable: 'Update available: {current} → {latest}',
         // Files
@@ -1264,7 +1271,11 @@ export const messages = {
         uninstallPartial: '⚠ Uninstall completed with errors.',
         removed: 'Removed',
         skippedLabel: 'Skipped',
-        errorsLabel: 'Errors'
+        errorsLabel: 'Errors',
+        cannotPrompt: 'Cannot ask for confirmation: nothing is attached to answer the prompt (non-interactive shell, CI, or a pipe).',
+        cannotPromptHint: 'Nothing has been changed. Re-run with --yes to confirm up front, or with --dry-run to preview the changes.',
+        promptClosed: 'The prompt was closed before an answer was given. Nothing has been changed.',
+        promptClosedMidRun: 'A prompt was closed part-way through. Steps already completed stay done; run `uds uninstall` again to finish.'
       }
     }
   },
@@ -2135,7 +2146,7 @@ export const messages = {
         missingSkillsHint: '提示：執行 `uds update` 安裝缺少的 Skills/斜線命令',
         // 提交前檢查是否真的會被 git 執行（uds init 寫了檢查檔，卻沒確認 git 會跑它——這裡只回報，不寫入）
         hookNotWiredTitle: '⚠ [pre-commit] {file} 已安裝，但 git 實際不會執行它。',
-        hookNotWiredOverride: '  git core.hooksPath 已設定為「{path}」——UDS 不會覆蓋它。請確認該路徑下的檔案也會執行 `npx uds check`，或自行改用：git config --local core.hooksPath .husky',
+        hookNotWiredOverride: '  git core.hooksPath 已設定為「{path}」——UDS 不會覆蓋它。請確認該路徑下的檔案也會執行 `universal-dev-standards check`（要用已安裝的 CLI——不要用短名稱 uds，它在 npm registry 上是不相干的套件），或自行改用：git config --local core.hooksPath .husky',
         hookNotWiredUnwired: '  git core.hooksPath 未設定，而 {file} 也不在 git 預設會讀取的路徑上。',
         hookNotWiredFix: '  修復方式（僅對此 clone 生效，不會進版控，其他人 clone 後要自己再跑一次）：git config --local core.hooksPath .husky',
         hookNotWiredFixNative: '  修復方式：把 core.hooksPath 改回預設（git config --local --unset core.hooksPath），或改在「{path}」底下也加上 `uds check`。',
@@ -2151,6 +2162,8 @@ export const messages = {
         // 2026-09-27 於 CI（windows-latest）實測。
         hookMissingShebangTitle: '⚠ [pre-commit] {file} 沒有 shebang 行——在 Windows 上 git 無法執行它。',
         hookMissingShebangFix: '  修復方式：在 {file} 的第一行加上 shebang `#!/bin/sh`（由 husky 管理的 hook，下次 `uds init` 動到它時會自動處理），或重新執行 `uds init`。',
+        hookBareUdsTitle: '⚠ [pre-commit] {file} 會請 npm 執行裸名稱 uds，而它在 npm registry 上是不相干的套件（不是本專案）。',
+        hookBareUdsFix: '  修復方式：執行 `uds update`——它會把 UDS 自己寫入的那一行換成只執行已安裝 UDS CLI 的寫法。你自己寫或改過的那一行不會被動，請自行改成 `universal-dev-standards check`。',
         // Summary mode (--summary)
         summary_mode: {
           title: 'UDS 狀態摘要',
@@ -2294,6 +2307,11 @@ export const messages = {
         currentVersion: '目前版本',
         latestVersion: '最新版本',
         upToDate: '✓ 標準已是最新版本。',
+        // pre-commit hook 遷移（npm registry 上的裸名稱 uds 不是本專案）
+        hookMigrated: '✓ .husky/pre-commit：已把舊版 UDS 寫入的那一行（它會請 npm 解析裸名稱 uds，而那不是本專案）換成只執行已安裝 UDS CLI 的寫法。',
+        hookWouldMigrate: '+ .husky/pre-commit：將把舊版 UDS 寫入的那一行（它會請 npm 解析裸名稱 uds，而那不是本專案）換成只執行已安裝 UDS CLI 的寫法。',
+        hookLegacyKept: '⚠ .husky/pre-commit 第 {line} 行（「{text}」）會請 npm 解析裸名稱 uds，而它在 npm registry 上是不相干的套件。這一行不是 UDS 寫入的原樣，所以沒有動它。請自行改成 universal-dev-standards check——需要在本專案或 PATH 上已安裝 UDS CLI。',
+        hookMigrateFailed: '⚠ 無法改寫 .husky/pre-commit：{error}。請 npm 解析裸名稱 uds 的那一行仍在，請自行改成 universal-dev-standards check。',
         newerVersion: '（你的版本比登錄庫更新：{version}）',
         updateAvailable: '有可用更新：{current} → {latest}',
         // Files
@@ -2520,7 +2538,11 @@ export const messages = {
         uninstallPartial: '⚠ 解除安裝完成但有錯誤。',
         removed: '已移除',
         skippedLabel: '已跳過',
-        errorsLabel: '錯誤'
+        errorsLabel: '錯誤',
+        cannotPrompt: '無法詢問確認：目前沒有可回答提示的終端機（非互動 shell、CI 或管線）。',
+        cannotPromptHint: '尚未變更任何檔案。請加上 --yes 事先確認，或加上 --dry-run 預覽變更。',
+        promptClosed: '提示在回答前被關閉。尚未變更任何檔案。',
+        promptClosedMidRun: '執行途中提示被關閉。已完成的步驟維持完成；請再執行一次 `uds uninstall` 完成其餘部分。'
       }
     }
   },
@@ -3407,7 +3429,7 @@ export const messages = {
         missingSkillsHint: '提示：执行 `uds update` 安装缺少的 Skills/斜线命令',
         // 提交前检查是否真的会被 git 执行（uds init 写了检查文件，却没确认 git 会跑它——这里只回报，不写入）
         hookNotWiredTitle: '⚠ [pre-commit] {file} 已安装，但 git 实际不会执行它。',
-        hookNotWiredOverride: '  git core.hooksPath 已设定为“{path}”——UDS 不会覆盖它。请确认该路径下的文件也会执行 `npx uds check`，或自行改用：git config --local core.hooksPath .husky',
+        hookNotWiredOverride: '  git core.hooksPath 已设定为“{path}”——UDS 不会覆盖它。请确认该路径下的文件也会执行 `universal-dev-standards check`（要用已安装的 CLI——不要用短名称 uds，它在 npm registry 上是不相干的包），或自行改用：git config --local core.hooksPath .husky',
         hookNotWiredUnwired: '  git core.hooksPath 未设定，而 {file} 也不在 git 默认会读取的路径上。',
         hookNotWiredFix: '  修复方式（仅对此 clone 生效，不会进版控，其他人 clone 后要自己再跑一次）：git config --local core.hooksPath .husky',
         hookNotWiredFixNative: '  修复方式：把 core.hooksPath 改回默认（git config --local --unset core.hooksPath），或改在“{path}”下也加上 `uds check`。',
@@ -3419,6 +3441,8 @@ export const messages = {
         // 2026-09-27 于 CI（windows-latest）实测。
         hookMissingShebangTitle: '⚠ [pre-commit] {file} 没有 shebang 行——在 Windows 上 git 无法执行它。',
         hookMissingShebangFix: '  修复方式：在 {file} 的第一行加上 shebang `#!/bin/sh`（由 husky 管理的 hook，下次 `uds init` 动到它时会自动处理），或重新运行 `uds init`。',
+        hookBareUdsTitle: '⚠ [pre-commit] {file} 会请 npm 执行裸名称 uds，而它在 npm registry 上是不相干的包（不是本项目）。',
+        hookBareUdsFix: '  修复方式：运行 `uds update`——它会把 UDS 自己写入的那一行换成只执行已安装 UDS CLI 的写法。你自己写或改过的那一行不会被动，请自行改成 `universal-dev-standards check`。',
         // Summary mode (--summary)
         summary_mode: {
           title: 'UDS 状态摘要',
@@ -3474,6 +3498,11 @@ export const messages = {
         currentVersion: '当前版本',
         latestVersion: '最新版本',
         upToDate: '✓ 标准是最新的。',
+        // pre-commit hook 迁移（npm registry 上的裸名称 uds 不是本项目）
+        hookMigrated: '✓ .husky/pre-commit：已把旧版 UDS 写入的那一行（它会请 npm 解析裸名称 uds，而那不是本项目）换成只执行已安装 UDS CLI 的写法。',
+        hookWouldMigrate: '+ .husky/pre-commit：将把旧版 UDS 写入的那一行（它会请 npm 解析裸名称 uds，而那不是本项目）换成只执行已安装 UDS CLI 的写法。',
+        hookLegacyKept: '⚠ .husky/pre-commit 第 {line} 行（“{text}”）会请 npm 解析裸名称 uds，而它在 npm registry 上是不相干的包。这一行不是 UDS 写入的原样，所以没有动它。请自行改成 universal-dev-standards check——需要在本项目或 PATH 上已安装 UDS CLI。',
+        hookMigrateFailed: '⚠ 无法改写 .husky/pre-commit：{error}。请 npm 解析裸名称 uds 的那一行仍在，请自行改成 universal-dev-standards check。',
         newerVersion: '（您有比注册表更新的版本：{version}）',
         updateAvailable: '有可用更新：{current} → {latest}',
         // Files
@@ -3700,7 +3729,11 @@ export const messages = {
         uninstallPartial: '⚠ 卸载完成但有错误。',
         removed: '已移除',
         skippedLabel: '已跳过',
-        errorsLabel: '错误'
+        errorsLabel: '错误',
+        cannotPrompt: '无法询问确认：当前没有可回答提示的终端（非交互 shell、CI 或管道）。',
+        cannotPromptHint: '尚未更改任何文件。请加上 --yes 提前确认，或加上 --dry-run 预览变更。',
+        promptClosed: '提示在回答前被关闭。尚未更改任何文件。',
+        promptClosedMidRun: '执行途中提示被关闭。已完成的步骤保持完成；请再运行一次 `uds uninstall` 完成其余部分。'
       }
     }
   }

package/src/installers/hooks-installer.js

@@ -31,12 +31,13 @@
  * @see core/turn-completion-integrity.md
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, readdirSync } from 'fs';
-import { join, dirname, basename } from 'path';
+import { existsSync, readFileSync, writeFileSync, copyFileSync, readdirSync } from 'fs';
+import { join, dirname, basename, relative } from 'path';
 import { fileURLToPath } from 'url';
 import { execFileSync } from 'child_process';
 import { load as parseYaml } from 'js-yaml';
 import { detectAITools } from '../utils/detector.js';
+import { newRecorder, mkdirTracked, recordFile, RECORD_KINDS } from '../core/install-records.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -172,7 +173,41 @@ function probeLanguageLimits(hooksDir, scripts) {
   return out;
 }
 
-export function installHooks(projectPath, { overwriteScripts = true } = {}) {
+/**
+ * Copy the shipped hook scripts (recursively — a hook may ship a directory beside
+ * it: locale packs, fixtures) into `<project>/scripts/hooks`, and RECORD every
+ * file this call actually wrote and every directory it had to create.
+ *
+ * `cpSync` did the copy before and returns nothing, which is why `uds uninstall`
+ * had no way to know which of the files under `scripts/hooks/` were UDS's — a
+ * directory an adopter's own hook scripts may share. A file that already exists
+ * and is byte-identical is not recorded (this call did not write it, so it
+ * proves nothing about who did); a file that exists, differs, and is not
+ * overwritten is left alone and not recorded.
+ *
+ * @param {string} srcDir  Shipped hooks directory
+ * @param {string} destDir Destination directory (absolute)
+ * @param {{ overwrite: boolean, recorder: object, projectPath: string }} ctx
+ */
+function copyTreeRecorded(srcDir, destDir, ctx) {
+  mkdirTracked(ctx.recorder, ctx.projectPath, destDir);
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    const src = join(srcDir, entry.name);
+    const dest = join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      copyTreeRecorded(src, dest, ctx);
+      continue;
+    }
+    if (existsSync(dest)) {
+      if (!ctx.overwrite) continue;
+      if (readFileSync(src).equals(readFileSync(dest))) continue;
+    }
+    copyFileSync(src, dest);
+    recordFile(ctx.recorder, ctx.projectPath, relative(ctx.projectPath, dest), RECORD_KINDS.HOOK_SCRIPT);
+  }
+}
+
+export function installHooks(projectPath, { overwriteScripts = true, recorder = newRecorder() } = {}) {
   const claudeDir = join(projectPath, '.claude');
   const settingsPath = join(claudeDir, 'settings.json');
   const hooksDir = join(projectPath, 'scripts', 'hooks');
@@ -187,11 +222,8 @@ export function installHooks(projectPath, { overwriteScripts = true } = {}) {
     return { installed: false, scriptsCount: 0, settingsPath, events, skipped };
   }
 
-  if (!existsSync(claudeDir)) mkdirSync(claudeDir, { recursive: true });
-  if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
-
-  // Recursive: a hook may ship a directory beside it (locale packs, fixtures).
-  cpSync(hookDir, hooksDir, { recursive: true, force: overwriteScripts });
+  mkdirTracked(recorder, projectPath, claudeDir);
+  copyTreeRecorded(hookDir, hooksDir, { overwrite: overwriteScripts, recorder, projectPath });
 
   let settings = {};
   if (existsSync(settingsPath)) {
@@ -217,6 +249,7 @@ export function installHooks(projectPath, { overwriteScripts = true } = {}) {
     events,
     skipped,
     languageLimits: probeLanguageLimits(hooksDir, scripts),
+    artifacts: recorder,
   };
 }
 
@@ -264,9 +297,8 @@ export const AGY_HOOK_COMMAND_LEGACY = `node scripts/hooks/${AGY_HOOK_SCRIPT}`;
  * `overwrite: false` keeps a script that already exists (an adopter may have
  * edited it); it is what `uds update --with-hooks` uses unless `--force` is given.
  */
-function copyHookScripts(hookDir, hooksDir, { overwrite = true } = {}) {
-  if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
-  cpSync(hookDir, hooksDir, { recursive: true, force: overwrite });
+function copyHookScripts(hookDir, hooksDir, { overwrite = true, recorder, projectPath } = {}) {
+  copyTreeRecorded(hookDir, hooksDir, { overwrite, recorder, projectPath });
 }
 
 /**
@@ -283,7 +315,7 @@ function copyHookScripts(hookDir, hooksDir, { overwrite = true } = {}) {
  * @param {string} projectPath
  * @returns {{ installed: boolean, settingsPath: string, event?: string, reason?: string }}
  */
-export function installCodexHooks(projectPath, { overwriteScripts = true } = {}) {
+export function installCodexHooks(projectPath, { overwriteScripts = true, recorder = newRecorder() } = {}) {
   const hooksJsonPath = join(projectPath, '.codex', 'hooks.json');
   const hookDir = hooksSourceDir();
 
@@ -291,9 +323,8 @@ export function installCodexHooks(projectPath, { overwriteScripts = true } = {})
     return { installed: false, settingsPath: hooksJsonPath, reason: `hook script not found: ${CODEX_HOOK_SCRIPT}` };
   }
 
-  const codexDir = join(projectPath, '.codex');
-  if (!existsSync(codexDir)) mkdirSync(codexDir, { recursive: true });
-  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts });
+  mkdirTracked(recorder, projectPath, join(projectPath, '.codex'));
+  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts, recorder, projectPath });
 
   let config = {};
   if (existsSync(hooksJsonPath)) {
@@ -310,7 +341,7 @@ export function installCodexHooks(projectPath, { overwriteScripts = true } = {})
   ]);
 
   writeFileSync(hooksJsonPath, JSON.stringify(config, null, 2) + '\n');
-  return { installed: true, settingsPath: hooksJsonPath, event: 'Stop' };
+  return { installed: true, settingsPath: hooksJsonPath, event: 'Stop', artifacts: recorder };
 }
 
 /**
@@ -323,7 +354,7 @@ export function installCodexHooks(projectPath, { overwriteScripts = true } = {})
  * @param {string} projectPath
  * @returns {{ installed: boolean, settingsPath: string, event?: string, reason?: string }}
  */
-export function installGeminiHooks(projectPath, { overwriteScripts = true } = {}) {
+export function installGeminiHooks(projectPath, { overwriteScripts = true, recorder = newRecorder() } = {}) {
   const settingsPath = join(projectPath, '.gemini', 'settings.json');
   const hookDir = hooksSourceDir();
 
@@ -331,9 +362,8 @@ export function installGeminiHooks(projectPath, { overwriteScripts = true } = {}
     return { installed: false, settingsPath, reason: `hook script not found: ${GEMINI_HOOK_SCRIPT}` };
   }
 
-  const geminiDir = join(projectPath, '.gemini');
-  if (!existsSync(geminiDir)) mkdirSync(geminiDir, { recursive: true });
-  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts });
+  mkdirTracked(recorder, projectPath, join(projectPath, '.gemini'));
+  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts, recorder, projectPath });
 
   let settings = {};
   if (existsSync(settingsPath)) {
@@ -349,7 +379,7 @@ export function installGeminiHooks(projectPath, { overwriteScripts = true } = {}
   ]);
 
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-  return { installed: true, settingsPath, event: 'AfterAgent' };
+  return { installed: true, settingsPath, event: 'AfterAgent', artifacts: recorder };
 }
 
 /**
@@ -377,7 +407,7 @@ export function installGeminiHooks(projectPath, { overwriteScripts = true } = {}
  * @param {string} projectPath
  * @returns {{ installed: boolean, settingsPath: string, event?: string, reason?: string }}
  */
-export function installAgyHooks(projectPath, { overwriteScripts = true } = {}) {
+export function installAgyHooks(projectPath, { overwriteScripts = true, recorder = newRecorder() } = {}) {
   const hooksJsonPath = join(projectPath, '.agents', 'hooks.json');
   const hookDir = hooksSourceDir();
 
@@ -397,9 +427,8 @@ export function installAgyHooks(projectPath, { overwriteScripts = true } = {}) {
     }
   }
 
-  const agentsDir = join(projectPath, '.agents');
-  if (!existsSync(agentsDir)) mkdirSync(agentsDir, { recursive: true });
-  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts });
+  mkdirTracked(recorder, projectPath, join(projectPath, '.agents'));
+  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts, recorder, projectPath });
 
   const command = AGY_HOOK_COMMAND;
   const entry = config[AGY_HOOK_NAME];
@@ -416,7 +445,7 @@ export function installAgyHooks(projectPath, { overwriteScripts = true } = {}) {
   config[AGY_HOOK_NAME] = { ...mine, Stop: stop };
 
   writeFileSync(hooksJsonPath, JSON.stringify(config, null, 2) + '\n');
-  return { installed: true, settingsPath: hooksJsonPath, event: 'Stop' };
+  return { installed: true, settingsPath: hooksJsonPath, event: 'Stop', artifacts: recorder };
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -574,9 +603,11 @@ const INSTALLERS = {
  * @param {string} projectPath
  * @param {string[]} tools
  * @param {{ plan?: boolean, overwriteScripts?: boolean }} [opts]
- * @returns {{ results: Array<{tool:string, outcome:'installed'|'unchanged'|'would-install'|'blocked'|'failed', path:string, why?:string, repaired?:boolean}>, scripts: {added:number, identical:number, kept:string[]} }}
+ * @returns {{ results: Array<{tool:string, outcome:'installed'|'unchanged'|'would-install'|'blocked'|'failed', path:string, why?:string, repaired?:boolean}>, scripts: {added:number, identical:number, kept:string[]}, artifacts: object }}
+ *   `artifacts` is the recorder of what this call wrote (see core/install-records.js);
+ *   the caller persists it into the manifest so `uds uninstall` can remove exactly that.
  */
-export function installMissingHooks(projectPath, tools, { plan = false, overwriteScripts = false } = {}) {
+export function installMissingHooks(projectPath, tools, { plan = false, overwriteScripts = false, recorder = newRecorder() } = {}) {
   // Measured BEFORE anything is copied: afterwards every script would read "identical".
   const scripts = scriptDiff(projectPath);
   const results = [];
@@ -585,9 +616,9 @@ export function installMissingHooks(projectPath, tools, { plan = false, overwrit
     if (st.status === 'present') { results.push({ tool, outcome: 'unchanged', path: st.path }); continue; }
     if (st.status === 'blocked') { results.push({ tool, outcome: 'blocked', path: st.path, why: st.why }); continue; }
     if (plan) { results.push({ tool, outcome: 'would-install', path: st.path, repaired: st.status === 'stale' }); continue; }
-    const r = INSTALLERS[tool](projectPath, { overwriteScripts });
+    const r = INSTALLERS[tool](projectPath, { overwriteScripts, recorder });
     if (r.installed) results.push({ tool, outcome: 'installed', path: r.settingsPath ?? st.path, repaired: st.status === 'stale' });
     else results.push({ tool, outcome: 'failed', path: r.settingsPath ?? st.path, why: r.reason ?? 'no standard produced a usable hook' });
   }
-  return { results, scripts };
+  return { results, scripts, artifacts: recorder };
 }