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

package/src/commands/open-work.js

@@ -0,0 +1,60 @@
+/**
+ * `uds open-work` — the open-work-tracking reference checks (OWT-017 / 018 / 019)
+ * as a command, so an adopter can run them from the npm package.
+ *
+ * This file holds no rules. The one body of them is
+ * `../utils/open-work-tracking.mjs`; this only turns commander's parsed
+ * arguments back into the argv that module's `main()` reads, so the command and
+ * `node scripts/check-open-work-tracking.mjs` cannot disagree.
+ *
+ * Exit codes are the module's and are not translated: 0 no violation, 1
+ * violation, 2 cannot decide (no structure found, git failed, or the checker's
+ * own self-test arms failed). 2 is NOT a pass. `process.exitCode` is set rather
+ * than calling `process.exit()`, so commander's post-action hook still runs.
+ *
+ * It is a reference decision procedure offered as evidence (OWT-015), not a
+ * gate, and its coverage is unknown and uncalibrated (OWT-011, OWT-016); the
+ * module prints both statements on every run.
+ *
+ * @module commands/open-work
+ */
+
+import { main } from '../utils/open-work-tracking.mjs';
+
+/** Append `--name value` when the option was given. */
+function withOption(argv, name, value) {
+  if (value !== undefined && value !== null) argv.push(name, String(value));
+  return argv;
+}
+
+function run(argv) {
+  process.exitCode = main(argv);
+}
+
+/** uds open-work next-action [files...] [--root DIR] [--id-pattern RE] — OWT-019 */
+export function openWorkNextActionCommand(files = [], options = {}) {
+  const argv = ['next-action'];
+  withOption(argv, '--root', options.root);
+  withOption(argv, '--id-pattern', options.idPattern);
+  run([...argv, ...files]);
+}
+
+/** uds open-work revision (--file PATH --base REV | --before FILE --after FILE) — OWT-018 */
+export function openWorkRevisionCommand(options = {}) {
+  const argv = ['revision'];
+  withOption(argv, '--file', options.file);
+  withOption(argv, '--base', options.base);
+  withOption(argv, '--before', options.before);
+  withOption(argv, '--after', options.after);
+  run(argv);
+}
+
+/** uds open-work separation [files...] — OWT-017 */
+export function openWorkSeparationCommand(files = []) {
+  run(['separation', ...files]);
+}
+
+/** uds open-work self-test — run the checker's own arms and nothing else */
+export function openWorkSelfTestCommand() {
+  run(['--self-test']);
+}

package/src/commands/update.js

@@ -46,6 +46,7 @@ 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 {
   promptSkillsInstallLocation,
   promptCommandsInstallation
@@ -451,6 +452,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
@@ -1827,6 +1837,87 @@ 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[]}}
  */
+/**
+ * `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();
+  }
+
+  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 } = installMissingHooks(projectPath, resolved.tools, {
+    plan: !!options.plan,
+    overwriteScripts: !!options.force,
+  });
+
+  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/i18n/messages.js

@@ -930,6 +930,7 @@ export const messages = {
         title: 'Universal Development Standards - Initialize',
         alreadyInitialized: '⚠ Standards already initialized in this project.',
         useUpdateOrDelete: 'Use `uds update` to update, or delete .standards/ to reinitialize.',
+        useUpdateWithHooks: 'To add enforcement hooks to this project (including for tools UDS began supporting after you initialized), run `uds update --with-hooks`.',
         // Detection
         detectingProject: 'Detecting project characteristics...',
         analysisComplete: 'Project analysis complete',
@@ -2188,6 +2189,7 @@ export const messages = {
         title: '通用開發標準 - 初始化',
         alreadyInitialized: '⚠ 此專案已初始化標準。',
         useUpdateOrDelete: '使用 `uds update` 更新，或刪除 .standards/ 重新初始化。',
+        useUpdateWithHooks: '要為這個專案補裝執行關卡（含 UDS 在你初始化之後才支援的工具），請執行 `uds update --with-hooks`。',
         // Detection
         detectingProject: '正在偵測專案特性...',
         analysisComplete: '專案分析完成',
@@ -3158,6 +3160,7 @@ export const messages = {
         title: '通用开发标准 - 初始化',
         alreadyInitialized: '⚠ 此项目已初始化标准。',
         useUpdateOrDelete: '使用 `uds update` 更新，或删除 .standards/ 重新初始化。',
+        useUpdateWithHooks: '要为这个项目补装执行关卡（含 UDS 在你初始化之后才支持的工具），请执行 `uds update --with-hooks`。',
         // Detection
         detectingProject: '正在检测项目特性...',
         analysisComplete: '项目分析完成',

package/src/installers/hooks-installer.js

@@ -36,6 +36,7 @@ import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
 import { execFileSync } from 'child_process';
 import { load as parseYaml } from 'js-yaml';
+import { detectAITools } from '../utils/detector.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -171,7 +172,7 @@ function probeLanguageLimits(hooksDir, scripts) {
   return out;
 }
 
-export function installHooks(projectPath) {
+export function installHooks(projectPath, { overwriteScripts = true } = {}) {
   const claudeDir = join(projectPath, '.claude');
   const settingsPath = join(claudeDir, 'settings.json');
   const hooksDir = join(projectPath, 'scripts', 'hooks');
@@ -190,7 +191,7 @@ export function installHooks(projectPath) {
   if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
 
   // Recursive: a hook may ship a directory beside it (locale packs, fixtures).
-  cpSync(hookDir, hooksDir, { recursive: true });
+  cpSync(hookDir, hooksDir, { recursive: true, force: overwriteScripts });
 
   let settings = {};
   if (existsSync(settingsPath)) {
@@ -258,10 +259,14 @@ export const AGY_HOOK_COMMAND = `node ../scripts/hooks/${AGY_HOOK_SCRIPT}`;
 // re-install repairs it and uninstall still removes it.
 export const AGY_HOOK_COMMAND_LEGACY = `node scripts/hooks/${AGY_HOOK_SCRIPT}`;
 
-/** Copy the shared hook scripts into the project, same as installHooks() does. */
-function copyHookScripts(hookDir, hooksDir) {
+/**
+ * Copy the shared hook scripts into the project, same as installHooks() does.
+ * `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 });
+  cpSync(hookDir, hooksDir, { recursive: true, force: overwrite });
 }
 
 /**
@@ -278,7 +283,7 @@ function copyHookScripts(hookDir, hooksDir) {
  * @param {string} projectPath
  * @returns {{ installed: boolean, settingsPath: string, event?: string, reason?: string }}
  */
-export function installCodexHooks(projectPath) {
+export function installCodexHooks(projectPath, { overwriteScripts = true } = {}) {
   const hooksJsonPath = join(projectPath, '.codex', 'hooks.json');
   const hookDir = hooksSourceDir();
 
@@ -288,7 +293,7 @@ export function installCodexHooks(projectPath) {
 
   const codexDir = join(projectPath, '.codex');
   if (!existsSync(codexDir)) mkdirSync(codexDir, { recursive: true });
-  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'));
+  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts });
 
   let config = {};
   if (existsSync(hooksJsonPath)) {
@@ -318,7 +323,7 @@ export function installCodexHooks(projectPath) {
  * @param {string} projectPath
  * @returns {{ installed: boolean, settingsPath: string, event?: string, reason?: string }}
  */
-export function installGeminiHooks(projectPath) {
+export function installGeminiHooks(projectPath, { overwriteScripts = true } = {}) {
   const settingsPath = join(projectPath, '.gemini', 'settings.json');
   const hookDir = hooksSourceDir();
 
@@ -328,7 +333,7 @@ export function installGeminiHooks(projectPath) {
 
   const geminiDir = join(projectPath, '.gemini');
   if (!existsSync(geminiDir)) mkdirSync(geminiDir, { recursive: true });
-  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'));
+  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts });
 
   let settings = {};
   if (existsSync(settingsPath)) {
@@ -372,7 +377,7 @@ export function installGeminiHooks(projectPath) {
  * @param {string} projectPath
  * @returns {{ installed: boolean, settingsPath: string, event?: string, reason?: string }}
  */
-export function installAgyHooks(projectPath) {
+export function installAgyHooks(projectPath, { overwriteScripts = true } = {}) {
   const hooksJsonPath = join(projectPath, '.agents', 'hooks.json');
   const hookDir = hooksSourceDir();
 
@@ -394,7 +399,7 @@ export function installAgyHooks(projectPath) {
 
   const agentsDir = join(projectPath, '.agents');
   if (!existsSync(agentsDir)) mkdirSync(agentsDir, { recursive: true });
-  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'));
+  copyHookScripts(hookDir, join(projectPath, 'scripts', 'hooks'), { overwrite: overwriteScripts });
 
   const command = AGY_HOOK_COMMAND;
   const entry = config[AGY_HOOK_NAME];
@@ -413,3 +418,176 @@ export function installAgyHooks(projectPath) {
   writeFileSync(hooksJsonPath, JSON.stringify(config, null, 2) + '\n');
   return { installed: true, settingsPath: hooksJsonPath, event: 'Stop' };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// `uds update --with-hooks` — hooks for a project that is already initialized.
+//
+// 🔴 Found 2026-09-29 installing the 6.14.0-beta.1 package into a fresh project:
+// hooks were only ever wired by `uds init --with-hooks`, and `uds init` refuses to
+// run twice ("Standards already initialized"). `uds update` had no hook option.
+// So an existing adopter could NEVER receive the hook for a tool UDS started
+// supporting after they initialized — and could not repair a hook file that was
+// never written. This is that door.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The tools that have a hook installer, in the order they are reported. */
+export const HOOK_CAPABLE_TOOLS = ['claude-code', 'codex', 'gemini-cli', 'antigravity'];
+
+/** detectAITools() keys are camelCase; manifests and flags use the kebab-case tool names. */
+const DETECTED_KEY_TO_TOOL = { claudeCode: 'claude-code', geminiCli: 'gemini-cli' };
+
+/**
+ * Which tools to install hooks for.
+ *
+ *   --ai-tool given → exactly those (validated); nothing is detected or guessed.
+ *   otherwise       → the manifest's tools ∪ what the project directory shows now.
+ *
+ * The union is the point: a project initialized before agy detection existed (or
+ * before the adopter started using agy) has no `antigravity` in its manifest, and
+ * detection alone finds it; a project whose marker files were deleted still has
+ * the tool in its manifest. Either source is enough, neither is required.
+ *
+ * @param {string} projectPath
+ * @param {object|null} manifest
+ * @param {{ aiTool?: string }} [options]
+ * @returns {{ tools: string[], explicit: boolean, unknown: string[], sources: Record<string,string[]> }}
+ */
+export function resolveHookTools(projectPath, manifest, options = {}) {
+  if (options.aiTool) {
+    const asked = String(options.aiTool).split(',').map((t) => t.trim().toLowerCase()).filter(Boolean);
+    const unknown = asked.filter((t) => !HOOK_CAPABLE_TOOLS.includes(t));
+    const tools = HOOK_CAPABLE_TOOLS.filter((t) => asked.includes(t));
+    return { tools, explicit: true, unknown, sources: Object.fromEntries(tools.map((t) => [t, ['--ai-tool']])) };
+  }
+  const sources = {};
+  const add = (tool, why) => {
+    if (!HOOK_CAPABLE_TOOLS.includes(tool)) return;
+    (sources[tool] ||= []).push(why);
+  };
+  for (const t of [...(manifest?.integrations ?? []), ...(manifest?.aiTools ?? [])]) add(t, 'manifest');
+  const detected = detectAITools(projectPath);
+  for (const [k, on] of Object.entries(detected)) if (on) add(DETECTED_KEY_TO_TOOL[k] ?? k, 'detected in the project');
+  for (const t of Object.keys(sources)) sources[t] = [...new Set(sources[t])];
+  return { tools: HOOK_CAPABLE_TOOLS.filter((t) => sources[t]), explicit: false, unknown: [], sources };
+}
+
+function readJson(path) {
+  if (!existsSync(path)) return { state: 'absent' };
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return { state: 'invalid', why: 'is not a JSON object' };
+    return { state: 'ok', value };
+  } catch {
+    return { state: 'invalid', why: 'is not valid JSON' };
+  }
+}
+
+const hasCommand = (entries, cmd) =>
+  Array.isArray(entries) && entries.some((e) => commandOf(e) === cmd);
+
+/**
+ * Is the hook for `tool` already in the project's config? Read-only.
+ *
+ * @returns {{ status: 'present'|'missing'|'stale'|'blocked', path: string, why?: string }}
+ *   present  every entry UDS would write is there — nothing to do
+ *   missing  none (or only part) of it is there
+ *   stale    agy's pre-fix command is there (does not resolve from agy's cwd)
+ *   blocked  the config file exists but cannot be merged safely (invalid JSON)
+ */
+export function hookStatus(projectPath, tool) {
+  if (tool === 'antigravity') {
+    const path = join(projectPath, '.agents', 'hooks.json');
+    const j = readJson(path);
+    if (j.state === 'absent') return { status: 'missing', path };
+    if (j.state === 'invalid') return { status: 'blocked', path, why: `.agents/hooks.json ${j.why}; left untouched` };
+    const stop = j.value[AGY_HOOK_NAME]?.Stop;
+    const cmds = Array.isArray(stop) ? stop.map((h) => h && h.command) : [];
+    if (cmds.includes(AGY_HOOK_COMMAND) && !cmds.includes(AGY_HOOK_COMMAND_LEGACY)) return { status: 'present', path };
+    return { status: cmds.includes(AGY_HOOK_COMMAND_LEGACY) ? 'stale' : 'missing', path };
+  }
+  if (tool === 'codex') {
+    const path = join(projectPath, '.codex', 'hooks.json');
+    const j = readJson(path);
+    if (j.state === 'absent') return { status: 'missing', path };
+    if (j.state === 'invalid') return { status: 'missing', path, why: 'unreadable; it would be rewritten by the installer' };
+    return { status: hasCommand(j.value.hooks?.Stop, `node scripts/hooks/${CODEX_HOOK_SCRIPT}`) ? 'present' : 'missing', path };
+  }
+  if (tool === 'gemini-cli') {
+    const path = join(projectPath, '.gemini', 'settings.json');
+    const j = readJson(path);
+    if (j.state === 'absent') return { status: 'missing', path };
+    if (j.state === 'invalid') return { status: 'missing', path, why: 'unreadable; it would be rewritten by the installer' };
+    return { status: hasCommand(j.value.hooks?.AfterAgent, `node scripts/hooks/${GEMINI_HOOK_SCRIPT}`) ? 'present' : 'missing', path };
+  }
+  if (tool === 'claude-code') {
+    const path = join(projectPath, '.claude', 'settings.json');
+    const { configs } = collectHookConfigs(standardsSourceDir(), hooksSourceDir());
+    if (Object.keys(configs).length === 0) return { status: 'blocked', path, why: 'no standard produced a usable hook' };
+    const j = readJson(path);
+    if (j.state === 'absent') return { status: 'missing', path };
+    if (j.state === 'invalid') return { status: 'missing', path, why: 'unreadable; it would be rewritten by the installer' };
+    for (const [event, entries] of Object.entries(configs)) {
+      const existing = j.value.hooks?.[event] ?? [];
+      if (mergeHookArray(existing, entries).length !== existing.length) return { status: 'missing', path };
+    }
+    return { status: 'present', path };
+  }
+  return { status: 'blocked', path: '', why: `no hook installer for ${tool}` };
+}
+
+/** Hook scripts UDS ships vs what the project already has: how many are new, identical, or edited. */
+function scriptDiff(projectPath) {
+  const src = hooksSourceDir();
+  const out = { added: 0, identical: 0, kept: [] };
+  if (!src) return out;
+  const walk = (dir, rel = '') => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) { walk(join(dir, e.name), r); continue; }
+      const dest = join(projectPath, 'scripts', 'hooks', r);
+      if (!existsSync(dest)) out.added++;
+      else if (readFileSync(dest).equals(readFileSync(join(dir, e.name)))) out.identical++;
+      else out.kept.push(r);
+    }
+  };
+  walk(src);
+  return out;
+}
+
+const INSTALLERS = {
+  'claude-code': (p, o) => installHooks(p, o),
+  codex: (p, o) => installCodexHooks(p, o),
+  'gemini-cli': (p, o) => installGeminiHooks(p, o),
+  antigravity: (p, o) => installAgyHooks(p, o),
+};
+
+/**
+ * Add the hooks that are missing to an already-initialized project.
+ *
+ * - A hook that is already there is not touched, and nothing is written for it.
+ * - The adopter's own hooks are never touched: every installer merges (Claude,
+ *   Codex, Gemini) or writes only under the key UDS owns (agy).
+ * - A hook script the project already has and that differs from this version is
+ *   KEPT unless `overwriteScripts` — it may have been edited. It is reported.
+ * - `plan: true` reads and reports, and writes nothing.
+ *
+ * @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[]} }}
+ */
+export function installMissingHooks(projectPath, tools, { plan = false, overwriteScripts = false } = {}) {
+  // Measured BEFORE anything is copied: afterwards every script would read "identical".
+  const scripts = scriptDiff(projectPath);
+  const results = [];
+  for (const tool of tools) {
+    const st = hookStatus(projectPath, tool);
+    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 });
+    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 };
+}

package/src/utils/detector.js

@@ -111,6 +111,50 @@ export function detectFramework(projectPath) {
   return detected;
 }
 
+/**
+ * Files and directories under `.agents/` that Antigravity (agy) owns.
+ *
+ * 🔴 Detection used to be `.agents/AGENTS.md` alone (2026-09-08). That file is one
+ * of the things agy reads but a project can use agy for a long time without ever
+ * creating it, so `uds init --with-hooks` in such a project never wired the hook
+ * (found 2026-09-29 installing 6.14.0-beta.1 into a fresh project).
+ *
+ * The markers below come from the agy 1.2.12 binary (`strings`: the literal path
+ * templates `.agents/rules/`, `.agents/workflows/`, `.agents/plugins/`,
+ * `.agents/hooks.json`, `.agents/skills.json`, `.agents/agents/`) and from
+ * antigravity.google/docs/hooks (project hooks live at `.agents/hooks.json`;
+ * "Rules" and "Workflows" are documented Antigravity concepts). Chosen: the ones
+ * documented or carried by the tool itself whose NAME is agy's — not the generic
+ * `agents/` or `skills.json`.
+ *
+ * ⚠️ `.agents/skills/` is NOT a marker. Codex reads project skills from the same
+ * `.agents/skills/` (measured 2026-09-08: only that arm made Codex see the
+ * skills), so a directory that both tools share cannot say which one is in use.
+ * A repo with root AGENTS.md plus `.agents/skills/` is Codex and must stay Codex.
+ *
+ * ⚠️ `.agents/hooks.json` is also the file `uds` itself writes for agy. Detecting
+ * on it is self-referential: after an install it proves the install happened, not
+ * that the adopter uses agy. It is kept because a hooks.json that someone else
+ * (the adopter, another tool) put there is real evidence, and because dropping it
+ * would make a re-run of the installer stop seeing the project it just wired.
+ *
+ * Not used: `~/.gemini/projects.json` lists the projects agy has opened. It is the
+ * tool's own registry and a strong signal, but it lives in the user's home, is
+ * machine-local, and would make the same repository detect differently on two
+ * machines. Detection stays a function of the project directory.
+ */
+export const ANTIGRAVITY_MARKERS = ['AGENTS.md', 'hooks.json', 'rules', 'workflows', 'plugins'];
+
+/**
+ * @param {string} projectPath
+ * @returns {boolean} true when `.agents/` carries something Antigravity owns
+ */
+export function detectAntigravity(projectPath) {
+  const dir = join(projectPath, '.agents');
+  if (!existsSync(dir)) return false;
+  return ANTIGRAVITY_MARKERS.some((m) => existsSync(join(dir, m)));
+}
+
 /**
  * Detect AI tools configured in the project
  * @param {string} projectPath - Path to the project
@@ -129,7 +173,8 @@ export function detectAITools(projectPath) {
     // Antigravity never read INSTRUCTIONS.md.
     // Measured 2026-09-08 with two positive controls in the same run: tokens planted in `AGENTS.md` and `.agents/AGENTS.md` both came back with correct attribution; the one in INSTRUCTIONS.md did not.
     // `.agents/AGENTS.md` is used rather than the repo root so it does not collide with Codex/OpenCode, which both target root AGENTS.md.
-    antigravity: existsSync(join(projectPath, '.agents', 'AGENTS.md')),
+    // See detectAntigravity() for the wider marker set and for what is deliberately NOT one.
+    antigravity: detectAntigravity(projectPath),
     // 🔴 Roo Code had a full entry in the path table (`.roo/skills/`, tier "complete"
     // in REGISTRY.json) and NO line here, so `uds init` could never install for it —
     // however correct those paths were. Found by `check:install-paths`, which walks