universal-dev-standards 6.14.0-beta.1 → 6.14.0-beta.3

package/src/commands/uninstall.js

@@ -3,7 +3,8 @@ import { select, checkbox, confirm } from '@inquirer/prompts';
 import { readManifest, manifestExists, writeManifest } from '../core/manifest.js';
 import { t } from '../i18n/messages.js';
 import { uninstallStandards } from '../uninstallers/standards-uninstaller.js';
-import { uninstallHook } from '../uninstallers/hook-uninstaller.js';
+import { uninstallHook, pruneCreatedDirs } from '../uninstallers/hook-uninstaller.js';
+import { forgetRecords } from '../core/install-records.js';
 import { uninstallIntegrations } from '../uninstallers/integration-uninstaller.js';
 import { uninstallSkills } from '../uninstallers/skills-uninstaller.js';
 
@@ -12,6 +13,35 @@ import { uninstallSkills } from '../uninstallers/skills-uninstaller.js';
  */
 const CATEGORIES = ['hooks', 'skills', 'integrations', 'standards'];
 
+/**
+ * Exit codes. Before these existed every path out of `uninstall` was 0 — a run
+ * that removed nothing because the prompt died looked exactly like a completed
+ * uninstall to CI and to the adopter's own scripts.
+ */
+const EXIT_NOT_INITIALIZED = 1;   // nothing to uninstall / manifest unreadable
+const EXIT_CANNOT_PROMPT = 2;     // needed an answer, nobody could give one (same as `uds update`)
+const EXIT_INTERRUPTED = 130;     // the prompt was closed before answering (SIGINT convention)
+
+/**
+ * Can anything answer a prompt? Decided BEFORE a prompt is drawn.
+ *
+ * `uds update` catches ExitPromptError instead (see confirmOrFail there) and
+ * explains why it avoids `isTTY`: a wrapped stdin can answer with isTTY unset.
+ * That reasoning is sound for a prompt that has already been drawn, but it leaves
+ * the visible symptom this command was reported for — the checkbox painted onto a
+ * pipe, then a stack trace. Here the question is asked first, and only stdin
+ * matters: prompts read from it. An answer that arrives anyway (a test double, a
+ * wrapper) is not blocked by ExitPromptError handling further down.
+ */
+function canPrompt() {
+  return Boolean(process.stdin.isTTY);
+}
+
+/** `@inquirer/prompts` throws this when stdin closes or the user presses Ctrl+C. */
+function isPromptClosed(err) {
+  return err?.name === 'ExitPromptError' || /force closed the prompt/i.test(err?.message || '');
+}
+
 /**
  * Uninstall command - remove UDS standards, integrations, skills, and hooks
  * @param {Object} options - Command options
@@ -25,19 +55,25 @@ export async function uninstallCommand(options) {
   console.log(chalk.bold(msg.title));
   console.log(chalk.gray('─'.repeat(50)));
 
-  // Check if UDS is initialized
+  // Check if UDS is initialized. A project with nothing to uninstall is not a
+  // successful uninstall: exit non-zero so a script can tell the two apart.
   if (!manifestExists(projectPath)) {
     console.log(chalk.yellow(common.notInitialized));
     console.log(chalk.gray(`  ${common.runInit}`));
+    process.exitCode = EXIT_NOT_INITIALIZED;
     return;
   }
 
   const manifest = readManifest(projectPath);
   if (!manifest) {
     console.log(chalk.red(common.couldNotReadManifest));
+    process.exitCode = EXIT_NOT_INITIALIZED;
     return;
   }
 
+  const includeUserLevel = options.all || false;
+  const dryRun = options.dryRun || false;
+
   // Determine which categories to uninstall
   let selectedCategories;
   if (options.all) {
@@ -48,20 +84,34 @@ export async function uninstallCommand(options) {
     selectedCategories = ['skills'];
   } else if (options.integrationsOnly) {
     selectedCategories = ['integrations'];
-  } else if (options.yes) {
-    // --yes without specific flag → all categories
+  } else if (options.yes || dryRun) {
+    // --yes without a specific flag → all categories.
+    // --dry-run → all categories too, and WITHOUT a prompt: a dry run writes
+    // nothing, so there is nothing to ask before showing what a run would do —
+    // and its whole use is to be runnable unattended (CI, a pipe). It used to
+    // draw the category checkbox even then, and die on it.
     selectedCategories = [...CATEGORIES];
   } else {
     // Interactive: checkbox selection
-    const categories = await checkbox({
-      message: msg.selectCategories,
-      choices: [
-        { name: `${msg.categoryHooks} (.husky/pre-commit, .claude/settings.json, .codex/hooks.json, .gemini/settings.json, .agents/hooks.json)`, value: 'hooks', checked: true },
-        { name: `${msg.categorySkills} (skills, commands)`, value: 'skills', checked: true },
-        { name: `${msg.categoryIntegrations} (CLAUDE.md, .cursorrules, ...)`, value: 'integrations', checked: true },
-        { name: `${msg.categoryStandards} (.standards/)`, value: 'standards', checked: true }
-      ]
-    });
+    if (!canPrompt()) {
+      refuseToPrompt(msg);
+      return;
+    }
+    let categories;
+    try {
+      categories = await checkbox({
+        message: msg.selectCategories,
+        choices: [
+          { name: `${msg.categoryHooks} (.husky/pre-commit, .claude/settings.json, .codex/hooks.json, .gemini/settings.json, .agents/hooks.json)`, value: 'hooks', checked: true },
+          { name: `${msg.categorySkills} (skills, commands)`, value: 'skills', checked: true },
+          { name: `${msg.categoryIntegrations} (CLAUDE.md, .cursorrules, ...)`, value: 'integrations', checked: true },
+          { name: `${msg.categoryStandards} (.standards/)`, value: 'standards', checked: true }
+        ]
+      });
+    } catch (err) {
+      if (reportClosedPrompt(err, msg)) return;
+      throw err;
+    }
 
     if (categories.length === 0) {
       console.log(chalk.yellow(msg.nothingSelected));
@@ -70,9 +120,6 @@ export async function uninstallCommand(options) {
     selectedCategories = categories;
   }
 
-  const includeUserLevel = options.all || false;
-  const dryRun = options.dryRun || false;
-
   // Gather preview: run all uninstallers in dry-run mode to build summary
   const preview = await gatherPreview(projectPath, manifest, selectedCategories, includeUserLevel);
 
@@ -87,10 +134,22 @@ export async function uninstallCommand(options) {
 
   // Confirm (unless --yes or --dry-run)
   if (!dryRun && !options.yes) {
-    const confirmed = await confirm({
-      message: msg.confirmUninstall,
-      default: false
-    });
+    // Not auto-confirmed when nobody can answer: an unattended shell must not get
+    // more permission to delete files than an interactive one is given.
+    if (!canPrompt()) {
+      refuseToPrompt(msg);
+      return;
+    }
+    let confirmed;
+    try {
+      confirmed = await confirm({
+        message: msg.confirmUninstall,
+        default: false
+      });
+    } catch (err) {
+      if (reportClosedPrompt(err, msg)) return;
+      throw err;
+    }
 
     if (!confirmed) {
       console.log(chalk.yellow(common.cancelled));
@@ -106,18 +165,52 @@ export async function uninstallCommand(options) {
 
   // Execute uninstallation in order: hooks → skills → integrations → standards
   console.log();
-  const results = await executeUninstall(
-    projectPath, manifest, selectedCategories,
-    { includeUserLevel, interactive: !options.yes }
-  );
+  let results;
+  try {
+    results = await executeUninstall(
+      projectPath, manifest, selectedCategories,
+      { includeUserLevel, interactive: !options.yes }
+    );
+  } catch (err) {
+    // A per-file question asked mid-run (which is why this cannot be checked up
+    // front) was closed. Earlier steps are already done and stay done.
+    if (!isPromptClosed(err)) throw err;
+    console.log();
+    console.log(chalk.red(msg.promptClosedMidRun));
+    console.log();
+    process.exitCode = EXIT_INTERRUPTED;
+    return;
+  }
 
   // Update or remove manifest
-  updateManifestAfterUninstall(projectPath, manifest, selectedCategories);
+  updateManifestAfterUninstall(projectPath, manifest, selectedCategories, collectDeletedPaths(results));
 
   // Display results
   displayResults(results, msg);
 }
 
+/** Say why a real run cannot proceed without --yes, and set the exit code. Nothing has been changed. */
+function refuseToPrompt(msg) {
+  console.log();
+  console.log(chalk.red(msg.cannotPrompt));
+  console.log(chalk.gray(`  ${msg.cannotPromptHint}`));
+  console.log();
+  process.exitCode = EXIT_CANNOT_PROMPT;
+}
+
+/**
+ * If `err` is "the prompt was closed before an answer", report it, set a non-zero
+ * exit code and return true. Any other error is the caller's to rethrow.
+ */
+function reportClosedPrompt(err, msg) {
+  if (!isPromptClosed(err)) return false;
+  console.log();
+  console.log(chalk.red(msg.promptClosed));
+  console.log();
+  process.exitCode = EXIT_INTERRUPTED;
+  return true;
+}
+
 /**
  * Gather preview of what will be removed (dry-run all uninstallers)
  */
@@ -125,7 +218,7 @@ async function gatherPreview(projectPath, manifest, categories, includeUserLevel
   const preview = {};
 
   if (categories.includes('hooks')) {
-    preview.hooks = uninstallHook(projectPath, { dryRun: true });
+    preview.hooks = uninstallHook(projectPath, { dryRun: true, manifest });
   }
   if (categories.includes('skills')) {
     preview.skills = uninstallSkills(projectPath, manifest, { dryRun: true, includeUserLevel });
@@ -136,10 +229,23 @@ async function gatherPreview(projectPath, manifest, categories, includeUserLevel
   if (categories.includes('standards')) {
     preview.standards = uninstallStandards(projectPath, { dryRun: true });
   }
+  if (categories.includes('hooks')) {
+    // Nothing is deleted yet in a preview, so folders are judged against what the
+    // steps above WOULD delete.
+    preview.folders = pruneCreatedDirs(projectPath, manifest, {
+      dryRun: true,
+      plannedDeletions: collectDeletedPaths(preview)
+    });
+  }
 
   return preview;
 }
 
+/** Every relative path the given step results deleted (or, for a preview, would delete). */
+function collectDeletedPaths(results) {
+  return Object.values(results).flatMap((r) => r.deletedPaths || []);
+}
+
 /**
  * Execute actual uninstallation
  */
@@ -148,7 +254,7 @@ async function executeUninstall(projectPath, manifest, categories, options) {
   const results = {};
 
   if (categories.includes('hooks')) {
-    results.hooks = uninstallHook(projectPath);
+    results.hooks = uninstallHook(projectPath, { manifest });
   }
   if (categories.includes('skills')) {
     results.skills = uninstallSkills(projectPath, manifest, { includeUserLevel });
@@ -163,6 +269,10 @@ async function executeUninstall(projectPath, manifest, categories, options) {
   if (categories.includes('standards')) {
     results.standards = uninstallStandards(projectPath);
   }
+  if (categories.includes('hooks')) {
+    // After everything else, so a folder that only held UDS files is empty by now.
+    results.folders = pruneCreatedDirs(projectPath, manifest);
+  }
 
   return results;
 }
@@ -188,7 +298,7 @@ function createIntegrationPromptFn() {
 /**
  * Update or remove manifest after uninstall
  */
-function updateManifestAfterUninstall(projectPath, manifest, categories) {
+function updateManifestAfterUninstall(projectPath, manifest, categories, deletedPaths = []) {
   const removedStandards = categories.includes('standards');
 
   if (removedStandards) {
@@ -196,8 +306,10 @@ function updateManifestAfterUninstall(projectPath, manifest, categories) {
     return;
   }
 
-  // Partial uninstall: update manifest to reflect removed items
-  const updated = { ...manifest };
+  // Partial uninstall: update manifest to reflect removed items. Install records
+  // for the paths just deleted go too — a record for a file that is gone would
+  // otherwise "prove" authorship of whatever a user later puts at that path.
+  const updated = forgetRecords({ ...manifest }, deletedPaths);
 
   if (categories.includes('skills')) {
     updated.skills = {
@@ -281,6 +393,8 @@ function displayResults(results, msg) {
     console.log(chalk.green(msg.uninstallSuccess));
   } else {
     console.log(chalk.yellow(msg.uninstallPartial));
+    // "Completed with errors" is not a success to whoever runs this from a script.
+    process.exitCode = 1;
   }
   console.log(chalk.gray(`  ${msg.removed}: ${totalRemoved}  ${msg.skippedLabel}: ${totalSkipped}  ${msg.errorsLabel}: ${totalErrors}`));
 }

package/src/commands/update.js

@@ -46,6 +46,9 @@ import {
 } from '../config/ai-agent-paths.js';
 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
@@ -451,6 +454,15 @@ export async function updateCommand(options) {
     return;
   }
 
+  // Handle --with-hooks (added 2026-09-29): install the enforcement hooks that are
+  // MISSING from an already-initialized project — the door `uds init --with-hooks`
+  // cannot be, because `uds init` refuses to run twice. Standalone like
+  // --claude-target and --sync-refs; and like them it honours --plan by writing nothing.
+  if (options.withHooks) {
+    await updateHooksOnly(projectPath, manifest, options);
+    return;
+  }
+
   // Handle --sync-refs option.
   // `--plan` is honoured here too. This branch is above the mode dispatch
   // because sync-refs is its own operation rather than a scope of the
@@ -488,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) {
@@ -1827,6 +1846,136 @@ 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]`
+ *
+ * Adds the enforcement hooks that are missing; a hook that is already there is not
+ * touched, and the adopter's own hooks are never touched (see installMissingHooks).
+ * Exit code 1 only when there is no hook-capable tool to act on, or an install failed:
+ * "nothing to do" is 0, "could not tell which tool" is not.
+ *
+ * @param {string} projectPath
+ * @param {object} manifest
+ * @param {{ plan?: boolean, force?: boolean, aiTool?: string, yes?: boolean }} options
+ * @returns {Promise<void>}
+ */
+export async function updateHooksOnly(projectPath, manifest, options = {}) {
+  const ignored = ['skills', 'commands', 'syncRefs', 'integrationsOnly', 'standardsOnly', 'apply', 'rollback', 'prune']
+    .filter((k) => options[k]).map((k) => `--${k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())}`);
+  if (ignored.length) {
+    console.log(chalk.yellow(`  ! --with-hooks does one thing and does not compose; ${ignored.join(', ')} ignored.`));
+    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 });
+
+  if (resolved.unknown.length) {
+    console.log(chalk.red(`  ✗ No hook installer for: ${resolved.unknown.join(', ')}`));
+    console.log(chalk.gray(`    Tools with hooks: ${capable}`));
+    console.log();
+    process.exitCode = 1;
+    return;
+  }
+  if (resolved.tools.length === 0) {
+    // Both non-interactive and interactive get the same message: there is no prompt to
+    // fall back to here, so the way to say which tool is spelled out instead.
+    console.log(chalk.yellow('  ⚠ Could not tell which AI tool to install hooks for.'));
+    console.log(chalk.gray('    Neither this project\'s manifest nor its files name one of: ' + capable + '.'));
+    console.log(chalk.gray('    Say which one:  uds update --with-hooks --ai-tool <tool>[,<tool>...]'));
+    console.log(chalk.gray('    e.g.            uds update --with-hooks --ai-tool antigravity'));
+    console.log(chalk.gray('    What is detected:  claude-code (.claude/ or CLAUDE.md) · codex (root AGENTS.md) · gemini-cli (GEMINI.md)'));
+    console.log(chalk.gray('                       antigravity (.agents/AGENTS.md, .agents/rules/, .agents/workflows/, .agents/plugins/ or .agents/hooks.json; .agents/skills/ is shared with Codex and does not count)'));
+    console.log();
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(chalk.bold(options.plan ? 'Hooks — plan (nothing is written)' : 'Hooks'));
+  for (const tool of resolved.tools) {
+    console.log(chalk.gray(`  ${tool}: ${resolved.sources[tool].join(', ')}`));
+  }
+
+  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 : '';
+    if (r.outcome === 'installed') console.log(chalk.green(`  ✓ ${r.tool}: installed${r.repaired ? ' (replaced an out-of-date UDS entry)' : ''} — ${rel}`));
+    else if (r.outcome === 'would-install') console.log(chalk.cyan(`  + ${r.tool}: would install${r.repaired ? ' (replacing an out-of-date UDS entry)' : ''} — ${rel}`));
+    else if (r.outcome === 'unchanged') console.log(chalk.gray(`  · ${r.tool}: already installed, not touched — ${rel}`));
+    else { failed = true; console.log(chalk.yellow(`  ⚠ ${r.tool}: not installed — ${r.why}`)); }
+  }
+  const installedAny = results.some((r) => r.outcome === 'installed' || r.outcome === 'would-install');
+  if (installedAny && scripts.kept.length) {
+    console.log(chalk.yellow(`  ! ${scripts.kept.length} hook script(s) in scripts/hooks/ differ from this UDS version and were kept: ${scripts.kept.slice(0, 5).join(', ')}${scripts.kept.length > 5 ? ', ...' : ''}`));
+    console.log(chalk.gray('    Add --force to overwrite them with the shipped versions.'));
+  }
+  if (results.some((r) => r.tool === 'antigravity' && r.outcome === 'installed')) {
+    console.log(chalk.yellow('    ⚠ Verified against a real agy session for a single turn without tool calls in `agy -p` mode only; multi-turn, tool-call turns and interactive mode are not yet verified.'));
+  }
+  if (results.some((r) => r.tool === 'codex' && r.outcome === 'installed')) {
+    console.log(chalk.yellow('    ⚠ Codex will not run it until you trust it: open Codex in this project, trust the project, then run /hooks and trust this hook.'));
+  }
+  if (!results.some((r) => r.outcome === 'installed' || r.outcome === 'would-install')) {
+    console.log(chalk.gray('  Nothing to add.'));
+  }
+  console.log();
+  if (failed) process.exitCode = 1;
+}
+
 export function regenerateIntegrations(projectPath, manifest) {
   const aiTools = manifest.aiTools || [];
 

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