universal-dev-standards 6.8.0 → 6.10.0

package/src/i18n/messages.js

@@ -100,12 +100,10 @@ export const messages = {
       question: 'Select content mode:',
       labels: {
         index: 'Standard',
-        full: 'Full Embed',
         minimal: 'Minimal'
       },
       choices: {
         index: 'Summary + task mapping, AI knows when to read which standard',
-        full: 'Embed all rules, AI can use immediately but larger file',
         minimal: 'File references only, best with Skills'
       },
       explanations: {
@@ -114,11 +112,6 @@ export const messages = {
           '  → AI can determine "which standard to read for which task"',
           '  → Balance between context usage and compliance'
         ],
-        full: [
-          '  → All rules embedded in config file (~10-15 KB)',
-          '  → AI needs no extra file reads, highest compliance',
-          '  → Best for short tasks or strict compliance projects'
-        ],
         minimal: [
           '  → Only contains .standards/ file list',
           '  → AI needs to actively read standard files',
@@ -328,7 +321,6 @@ export const messages = {
       warning: 'Changing Content Mode will regenerate all AI tool config files',
       explanations: {
         index: '  → AI will determine when to read standards based on task mapping',
-        full: '  → All rules embedded directly, highest AI compliance',
         minimal: '  → AI must actively read standards, recommend using with Skills'
       }
     },
@@ -751,6 +743,9 @@ export const messages = {
         unchanged: 'unchanged',
         modified: 'modified',
         missing: 'missing',
+        retired: 'no longer shipped by UDS',
+        retiredHeader: '{count} tracked file(s) are gone because UDS stopped shipping them. That is the migration completed, not a fault:',
+        retiredHint: 'Run `uds update` to drop their manifest records. `--restore` cannot bring them back — there is no source upstream.',
         existsNoHash: 'exists, no hash',
         summary: 'Summary: {unchanged} unchanged, {modified} modified, {missing} missing',
         // Actions available
@@ -849,6 +844,13 @@ export const messages = {
         refsInSync: '{path}: references in sync ({count} refs)',
         noIntegrationRefs: 'No integration files with standard references found.',
         runSyncRefs: 'Run `uds update --sync-refs` to fix reference issues.',
+        runIntegrationsOnly: 'Run `uds update --integrations-only` to regenerate integration files.',
+        danglingRefs: 'references files that are not on disk:',
+        brokenMentions: 'mentions paths that do not exist in this project:',
+        brokenMentionsFix: 'These are usually outside the UDS block, left by an older install. UDS does not rewrite text it did not write — correct them by hand or delete the line.',
+        danglingRefsFix: 'Run `uds update --integrations-only` to regenerate them.',
+        commandsUntracked: '{count} installed command file(s) are covered by no hash — integrity is not checked for them',
+        commandsUntrackedFix: 'Run `uds update --commands` to record them again.',
         // CLI update
         checkingCliUpdates: 'Checking for CLI updates...',
         couldNotCheckUpdates: 'ℹ Could not check for CLI updates (offline mode)',
@@ -934,7 +936,6 @@ export const messages = {
         standardsScopeLean: 'Lean (Skills handle the rest)',
         standardsScopeComplete: 'Complete',
         contentModeLabel: 'Content Mode',
-        contentModeFull: 'Full Embed',
         contentModeIndex: 'Standard (recommended)',
         contentModeMinimal: 'Minimal (core only)',
         displayLanguageLabel: 'Display Language',
@@ -969,7 +970,10 @@ export const messages = {
         generatingAgentsMd: 'Generating AGENTS.md (universal summary)...',
         generatedAgentsMd: 'Generated AGENTS.md (universal summary)',
         couldNotGenerateAgentsMd: 'Could not generate AGENTS.md',
-        installingSkills: 'Installing Claude Code Skills...',
+        installingSkills: 'Installing Skills...',
+        // Named per detected tool, never per one tool: the install now goes to each
+        // tool's own path (XSPEC-408 §18.3), so a Claude-only label would be a lie.
+        skillsPathUnknown: 'no verified skills path for this tool — nothing was installed for it',
         installedSkills: 'Installed {count} Skills to {locations}',
         installedSkillsWithErrors: 'Installed {count} Skills with {errors} errors',
         // P1-CLI-1: locale fallback summary (printed after install when some
@@ -1026,6 +1030,7 @@ export const messages = {
         syncingIntegrations: 'Syncing integration files...',
         syncedIntegrations: 'Synced {count} integration files',
         prunedOrphanedBlockHashes: 'Pruned {count} orphaned integration hash(es): {files}',
+        droppedRetiredHashes: 'Dropped {count} manifest record(s) for files UDS no longer ships and that are already gone:',
         // Success
         updateSuccess: '✓ Standards updated successfully!',
         versionUpdated: 'Version: {current} → {latest}',
@@ -1053,6 +1058,7 @@ export const messages = {
         // Sync refs
         syncingRefs: 'Syncing integration references...',
         noIntegrationConfigs: '⚠ No integration configurations found in manifest.',
+        integrationConfigsBackfilled: 'Rebuilt integration config for {count} file(s) from the manifest.',
         integrationConfigsRequired: 'Integration configs are required for reference sync.',
         thisHappensWhen: 'This happens when:',
         oldVersion: '- The project was initialized with an older version of UDS',
@@ -1334,12 +1340,10 @@ export const messages = {
       question: '選擇內容模式：',
       labels: {
         index: '標準',
-        full: '完整嵌入',
         minimal: '最小化'
       },
       choices: {
         index: '摘要 + 任務對照表，AI 知道何時讀哪個規範',
-        full: '完整嵌入所有規則，AI 立即可用但檔案較大',
         minimal: '僅檔案參考，適合搭配 Skills 使用'
       },
       explanations: {
@@ -1348,11 +1352,6 @@ export const messages = {
           '  → AI 能判斷「做什麼任務時要讀哪個規範」',
           '  → 平衡 Context 使用量和合規程度'
         ],
-        full: [
-          '  → 所有規則直接嵌入設定檔（檔案約 10-15 KB）',
-          '  → AI 無需額外讀檔，合規率最高',
-          '  → 適合短期任務或需要嚴格遵循的專案'
-        ],
         minimal: [
           '  → 僅包含 .standards/ 檔案清單',
           '  → AI 需要主動讀取規範檔案',
@@ -1562,7 +1561,6 @@ export const messages = {
       warning: '變更 Content Mode 將重新生成所有 AI 工具設定檔',
       explanations: {
         index: '  → AI 會根據任務對照表判斷何時讀取規範',
-        full: '  → 所有規則直接嵌入，AI 合規率最高',
         minimal: '  → AI 需主動讀取規範，建議搭配 Skills'
       }
     },
@@ -1985,6 +1983,9 @@ export const messages = {
         unchanged: '未變更',
         modified: '已修改',
         missing: '遺失',
+        retired: 'UDS 已不再出貨',
+        retiredHeader: '有 {count} 個被追蹤的檔案不見了，原因是 UDS 已不再出貨。那是遷移完成的樣子，不是故障：',
+        retiredHint: '執行 `uds update` 清掉它們在 manifest 的紀錄。`--restore` 救不回來——上游已經沒有來源。',
         existsNoHash: '存在，無 hash',
         summary: '摘要：{unchanged} 未變更，{modified} 已修改，{missing} 遺失',
         // Actions available
@@ -2083,6 +2084,13 @@ export const messages = {
         refsInSync: '{path}：參考已同步（{count} 個參考）',
         noIntegrationRefs: '找不到有標準參考的整合檔案。',
         runSyncRefs: '執行 `uds update --sync-refs` 修復參考問題。',
+        runIntegrationsOnly: '執行 `uds update --integrations-only` 重新產生整合檔案。',
+        danglingRefs: '引用了磁碟上不存在的檔案：',
+        brokenMentions: '提到了本專案裡不存在的路徑：',
+        brokenMentionsFix: '這些通常在 UDS 區塊之外，是舊版安裝留下的。UDS 不會改寫不是它寫的文字——請手動更正或刪掉那一行。',
+        danglingRefsFix: '執行 `uds update --integrations-only` 重新產生。',
+        commandsUntracked: '{count} 個已安裝的斜線命令沒有任何雜湊涵蓋——這些檔案的完整性沒有被檢查',
+        commandsUntrackedFix: '執行 `uds update --commands` 重新記錄。',
         // CLI update
         checkingCliUpdates: '正在檢查 CLI 更新...',
         couldNotCheckUpdates: 'ℹ 無法檢查 CLI 更新（離線模式）',
@@ -2168,7 +2176,6 @@ export const messages = {
         standardsScopeLean: '精簡（Skills 處理其餘）',
         standardsScopeComplete: '完整',
         contentModeLabel: '內容模式',
-        contentModeFull: '完整嵌入',
         contentModeIndex: '標準（推薦）',
         contentModeMinimal: '最小（僅核心）',
         displayLanguageLabel: '顯示語言',
@@ -2203,7 +2210,8 @@ export const messages = {
         generatingAgentsMd: '產生 AGENTS.md（通用摘要）中...',
         generatedAgentsMd: '已產生 AGENTS.md（通用摘要）',
         couldNotGenerateAgentsMd: '無法產生 AGENTS.md',
-        installingSkills: '安裝 Claude Code Skills 中...',
+        installingSkills: '安裝 Skills 中...',
+        skillsPathUnknown: '沒有查證過的 skills 路徑，這個工具沒有安裝任何東西',
         installedSkills: '已安裝 {count} 個 Skills 到 {locations}',
         installedSkillsWithErrors: '已安裝 {count} 個 Skills，有 {errors} 個錯誤',
         // P1-CLI-1：locale fallback 摘要（安裝結束後顯示，列出沒有對應語系變體而退回英文來源的 skill）
@@ -2259,6 +2267,7 @@ export const messages = {
         syncingIntegrations: '同步整合檔案中...',
         syncedIntegrations: '已同步 {count} 個整合檔案',
         prunedOrphanedBlockHashes: '已清除 {count} 個孤兒整合雜湊：{files}',
+        droppedRetiredHashes: '已清掉 {count} 筆 manifest 紀錄——這些檔案 UDS 已不再出貨，而且本來就已經不在了：',
         // Success
         updateSuccess: '✓ 標準更新成功！',
         versionUpdated: '版本：{current} → {latest}',
@@ -2286,6 +2295,7 @@ export const messages = {
         // Sync refs
         syncingRefs: '同步整合參考中...',
         noIntegrationConfigs: '⚠ manifest 中找不到整合設定。',
+        integrationConfigsBackfilled: '已從 manifest 重建 {count} 個整合檔的設定。',
         integrationConfigsRequired: '參考同步需要整合設定。',
         thisHappensWhen: '這會發生在：',
         oldVersion: '- 專案使用較舊版本的 UDS 初始化',
@@ -2567,12 +2577,10 @@ export const messages = {
       question: '选择内容模式：',
       labels: {
         index: '标准',
-        full: '完整嵌入',
         minimal: '最小化'
       },
       choices: {
         index: '摘要 + 任务对照表，AI 知道何时读哪个规范',
-        full: '完整嵌入所有规则，AI 立即可用但文件较大',
         minimal: '仅文件参考，适合搭配 Skills 使用'
       },
       explanations: {
@@ -2581,11 +2589,6 @@ export const messages = {
           '  → AI 能判断"做什么任务时要读哪个规范"',
           '  → 平衡 Context 使用量和合规程度'
         ],
-        full: [
-          '  → 所有规则直接嵌入配置文件（文件约 10-15 KB）',
-          '  → AI 无需额外读档，合规率最高',
-          '  → 适合短期任务或需要严格遵循的项目'
-        ],
         minimal: [
           '  → 仅包含 .standards/ 文件清单',
           '  → AI 需要主动读取规范文件',
@@ -2795,7 +2798,6 @@ export const messages = {
       warning: '变更 Content Mode 将重新生成所有 AI 工具配置文件',
       explanations: {
         index: '  → AI 会根据任务对照表判断何时读取规范',
-        full: '  → 所有规则直接嵌入，AI 合规率最高',
         minimal: '  → AI 需主动读取规范，建议搭配 Skills'
       }
     },
@@ -3144,7 +3146,6 @@ export const messages = {
         standardsScopeLean: '精简（Skills 处理其余）',
         standardsScopeComplete: '完整',
         contentModeLabel: '内容模式',
-        contentModeFull: '完整嵌入',
         contentModeIndex: '标准（推荐）',
         contentModeMinimal: '最小（仅核心）',
         displayLanguageLabel: '显示语言',
@@ -3234,6 +3235,9 @@ export const messages = {
         unchanged: '未更改',
         modified: '已修改',
         missing: '缺失',
+        retired: 'UDS 已不再发布',
+        retiredHeader: '有 {count} 个被追踪的文件不见了，原因是 UDS 已不再发布。那是迁移完成的样子，不是故障：',
+        retiredHint: '执行 `uds update` 清掉它们在 manifest 的记录。`--restore` 救不回来——上游已经没有来源。',
         existsNoHash: '存在，无哈希',
         summary: '摘要：{unchanged} 未更改，{modified} 已修改，{missing} 缺失',
         // Actions available
@@ -3332,6 +3336,13 @@ export const messages = {
         refsInSync: '{path}：引用已同步（{count} 个引用）',
         noIntegrationRefs: '未找到包含标准引用的集成文件。',
         runSyncRefs: '执行 `uds update --sync-refs` 修复引用问题。',
+        runIntegrationsOnly: '执行 `uds update --integrations-only` 重新生成集成文件。',
+        danglingRefs: '引用了磁盘上不存在的文件：',
+        brokenMentions: '提到了本项目里不存在的路径：',
+        brokenMentionsFix: '这些通常在 UDS 区块之外，是旧版安装留下的。UDS 不会改写不是它写的文字——请手动更正或删掉那一行。',
+        danglingRefsFix: '执行 `uds update --integrations-only` 重新生成。',
+        commandsUntracked: '{count} 个已安装的斜杠命令没有任何哈希覆盖——这些文件的完整性没有被检查',
+        commandsUntrackedFix: '执行 `uds update --commands` 重新记录。',
         // CLI update
         checkingCliUpdates: '检查 CLI 更新...',
         couldNotCheckUpdates: 'ℹ 无法检查 CLI 更新（离线模式）',
@@ -3421,6 +3432,7 @@ export const messages = {
         syncingIntegrations: '正在同步集成文件...',
         syncedIntegrations: '已同步 {count} 个集成文件',
         prunedOrphanedBlockHashes: '已清除 {count} 个孤儿集成哈希：{files}',
+        droppedRetiredHashes: '已清掉 {count} 笔 manifest 记录——这些文件 UDS 已不再发布，而且本来就已经不在了：',
         // Success
         updateSuccess: '✓ 标准更新成功！',
         versionUpdated: '版本：{current} → {latest}',
@@ -3448,6 +3460,7 @@ export const messages = {
         // Sync refs
         syncingRefs: '正在同步集成引用...',
         noIntegrationConfigs: '⚠ manifest 中未找到集成配置。',
+        integrationConfigsBackfilled: '已从 manifest 重建 {count} 个集成文件的配置。',
         integrationConfigsRequired: '引用同步需要集成配置。',
         thisHappensWhen: '发生这种情况时：',
         oldVersion: '- 项目使用旧版 UDS 初始化',

package/src/installers/hooks-installer.js

@@ -1,105 +1,197 @@
 /**
  * UDS Hook Installer
  *
- * Copies hook scripts and generates/merges .claude/settings.json
- * with hook configurations.
+ * Copies hook scripts and merges .claude/settings.json with hook configurations
+ * derived from the `enforcement:` blocks of the shipped standards.
  *
  * Key constraints:
  * - MUST merge, never overwrite existing settings.json
  * - MUST be idempotent (no duplicate hooks on re-install)
+ * - MUST emit the hook handler shape Claude Code actually executes
+ *
+ * 🔴 Three defects fixed here on 2026-09-08, each of which failed silently and
+ * all three of which were present at once:
+ *
+ *   1. Hook entries were written as bare strings (`hooks: ['node x.js']`).
+ *      Measured with a two-arm run — a bare-string entry and an object entry
+ *      side by side in the same event of the same session: the object ran, the
+ *      bare string did not. Claude Code dispatches on `type`, and an entry
+ *      without one is skipped. settings.json stays valid JSON, the install
+ *      reports success, and nothing ever runs.
+ *   2. The hook scripts were resolved from `<repo>/scripts/hooks`, which is
+ *      outside the published package (`npm pack` listed 1 file matching
+ *      "hooks": this installer). Adopters installing from npm copied zero
+ *      scripts and still got `installed: true`.
+ *   3. The event/script list was hardcoded here, so a standard declaring an
+ *      `enforcement:` block got no hook unless someone also remembered to edit
+ *      this file. It is now derived by walking the standards.
  *
  * @module installers/hooks-installer
  * @see docs/specs/SPEC-HOOKS-001-core-standard-hooks.md (REQ-4)
+ * @see core/turn-completion-integrity.md
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'fs';
-import { join, dirname } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, cpSync, readdirSync } from 'fs';
+import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
+import { execFileSync } from 'child_process';
+import { load as parseYaml } from 'js-yaml';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-const HOOK_CONFIGS = {
-  PreToolUse: [
-    {
-      matcher: 'Bash',
-      hooks: ['node scripts/hooks/check-dangerous-cmd.js'],
-    },
-  ],
-  PostToolUse: [
-    {
-      matcher: 'Bash',
-      hooks: ['node scripts/hooks/check-logging-standard.js'],
-    },
-  ],
-  UserPromptSubmit: [
-    {
-      matcher: '',
-      hooks: ['node scripts/hooks/validate-commit-msg.js'],
-    },
-  ],
-};
-
-const HOOK_SCRIPTS = [
-  'validate-commit-msg.js',
-  'check-dangerous-cmd.js',
-  'check-logging-standard.js',
-];
+/** Prefer the bundled copy (present in the npm package), fall back to the repo. */
+function resolveDir(bundledRel, repoRel) {
+  const bundled = join(__dirname, '..', '..', 'bundled', ...bundledRel);
+  if (existsSync(bundled)) return bundled;
+  const repo = join(__dirname, '..', '..', '..', ...repoRel);
+  return existsSync(repo) ? repo : null;
+}
+
+export const standardsSourceDir = () => resolveDir(['ai', 'standards'], ['ai', 'standards']);
+export const hooksSourceDir = () => resolveDir(['hooks'], ['scripts', 'hooks']);
+
+/**
+ * Claude Code's matcher is a string. Some standards declare it as an object
+ * (`matcher: { tool: Bash }`), which would be written into settings.json
+ * verbatim and never match anything.
+ */
+function normalizeMatcher(matcher) {
+  if (typeof matcher === 'string') return matcher;
+  if (matcher && typeof matcher === 'object' && typeof matcher.tool === 'string') return matcher.tool;
+  return '';
+}
+
+/**
+ * Walk the shipped standards and build the hook configuration from every
+ * complete `enforcement:` block.
+ *
+ * @param {string|null} stdDir - directory of *.ai.yaml standards
+ * @param {string|null} hookDir - directory the hook scripts live in
+ * @returns {{ configs: Object, scripts: string[], skipped: Array<{id: string, why: string}> }}
+ */
+export function collectHookConfigs(stdDir, hookDir) {
+  const configs = {};
+  const scripts = [];
+  const skipped = [];
+  if (!stdDir) return { configs, scripts, skipped: [{ id: '*', why: 'standards directory not found' }] };
+
+  for (const file of readdirSync(stdDir).filter((f) => f.endsWith('.ai.yaml')).sort()) {
+    let std;
+    try {
+      std = parseYaml(readFileSync(join(stdDir, file), 'utf-8'));
+    } catch {
+      skipped.push({ id: file, why: 'unparseable YAML' });
+      continue;
+    }
+    const e = std && std.enforcement;
+    if (!e) continue;
+
+    const id = (std && std.id) || file;
+    if (typeof e.trigger !== 'string' || !e.trigger || typeof e.hook_script !== 'string' || !e.hook_script) {
+      // A block missing either field used to compile to hooks["undefined"]:
+      // [{ hooks: ["node undefined"] }] with no error at any layer.
+      skipped.push({ id, why: 'enforcement block missing trigger or hook_script' });
+      continue;
+    }
+
+    const rel = e.hook_script.replace(/^scripts\/hooks\//, '');
+    if (hookDir && !existsSync(join(hookDir, rel))) {
+      skipped.push({ id, why: `hook script not found: ${e.hook_script}` });
+      continue;
+    }
+
+    (configs[e.trigger] ||= []).push({
+      matcher: normalizeMatcher(e.matcher),
+      hooks: [{ type: 'command', command: `node scripts/hooks/${rel}` }],
+    });
+    scripts.push(rel);
+  }
+  return { configs, scripts, skipped };
+}
+
+/** The command string an entry runs, whatever shape it is stored in. */
+function commandOf(entry) {
+  const h = entry && entry.hooks && entry.hooks[0];
+  if (typeof h === 'string') return h;
+  return h && typeof h.command === 'string' ? h.command : undefined;
+}
 
 /**
- * Deep merge hook arrays, deduplicating by hook script path.
- * @param {Array} existing - Existing hook entries
- * @param {Array} incoming - New hook entries to merge
- * @returns {Array} Merged array without duplicates
+ * Merge hook arrays, deduplicating by (command, matcher).
+ * Existing entries are never rewritten — an adopter may have edited them.
  */
-function mergeHookArray(existing, incoming) {
+export function mergeHookArray(existing, incoming) {
   const result = [...existing];
   for (const entry of incoming) {
-    const hookScript = entry.hooks?.[0];
-    const isDuplicate = result.some(
-      (e) => e.hooks?.[0] === hookScript && e.matcher === entry.matcher
-    );
-    if (!isDuplicate) {
-      result.push(entry);
-    }
+    const cmd = commandOf(entry);
+    const dup = result.some((e) => commandOf(e) === cmd && e.matcher === entry.matcher);
+    if (!dup) result.push(entry);
   }
   return result;
 }
 
 /**
  * Install UDS hooks into a target project.
- * - Copies hook scripts to scripts/hooks/
- * - Creates or merges .claude/settings.json with hook configs
  *
  * @param {string} projectPath - Target project root path
- * @returns {{ installed: boolean, scriptsCount: number, settingsPath: string }}
+ * @returns {{ installed: boolean, scriptsCount: number, settingsPath: string, events: string[], skipped: Array }}
+ */
+/**
+ * Which installed hooks only work in some languages, asked of the hooks themselves.
+ *
+ * turn-completion-integrity R8 says an unsupported language must be declared,
+ * and the hook already answers `--languages`. Restating that list here would
+ * make a second hand-maintained copy of it, and the copy would drift — quietly,
+ * because both halves keep looking like valid data.
+ *
+ * 🔴 Why it matters at all: a prose-reading hook in a language it does not ship
+ * is installed, running, and structurally unable to fire. Its output is
+ * byte-identical to a turn with nothing wrong. Without this line the adopter
+ * has no way to tell those apart, ever.
+ *
+ * A hook with no such flag simply produces nothing here; failure is not an
+ * error, because "cannot introspect" must not block an install.
  */
+function probeLanguageLimits(hooksDir, scripts) {
+  const out = [];
+  for (const rel of new Set(scripts)) {
+    const abs = join(hooksDir, basename(rel));
+    if (!existsSync(abs)) continue;
+    try {
+      const text = execFileSync(process.execPath, [abs, '--languages'], {
+        encoding: 'utf-8',
+        timeout: 5000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
+      if (text) out.push({ script: basename(rel), languages: text });
+    } catch {
+      // no --languages, or it refused: nothing to declare.
+    }
+  }
+  return out;
+}
+
 export function installHooks(projectPath) {
   const claudeDir = join(projectPath, '.claude');
   const settingsPath = join(claudeDir, 'settings.json');
+  const hooksDir = join(projectPath, 'scripts', 'hooks');
 
-  // Ensure .claude/ directory exists
-  if (!existsSync(claudeDir)) {
-    mkdirSync(claudeDir, { recursive: true });
-  }
+  const stdDir = standardsSourceDir();
+  const hookDir = hooksSourceDir();
+  const { configs, scripts, skipped } = collectHookConfigs(stdDir, hookDir);
+  const events = Object.keys(configs);
 
-  // Copy hook scripts
-  const hooksDir = join(projectPath, 'scripts', 'hooks');
-  if (!existsSync(hooksDir)) {
-    mkdirSync(hooksDir, { recursive: true });
+  if (events.length === 0) {
+    // Reporting success here is what let three separate breakages ship.
+    return { installed: false, scriptsCount: 0, settingsPath, events, skipped };
   }
 
-  const sourceHooksDir = join(__dirname, '..', '..', '..', 'scripts', 'hooks');
-  let scriptsCount = 0;
-  for (const script of HOOK_SCRIPTS) {
-    const src = join(sourceHooksDir, script);
-    const dest = join(hooksDir, script);
-    if (existsSync(src)) {
-      copyFileSync(src, dest);
-      scriptsCount++;
-    }
-  }
+  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 });
 
-  // Read or create settings.json
   let settings = {};
   if (existsSync(settingsPath)) {
     try {
@@ -108,21 +200,21 @@ export function installHooks(projectPath) {
       settings = {};
     }
   }
+  if (!settings.hooks) settings.hooks = {};
 
-  // Merge hooks
-  if (!settings.hooks) {
-    settings.hooks = {};
-  }
-
-  for (const [event, entries] of Object.entries(HOOK_CONFIGS)) {
-    if (!settings.hooks[event]) {
-      settings.hooks[event] = [];
-    }
+  for (const [event, entries] of Object.entries(configs)) {
+    if (!settings.hooks[event]) settings.hooks[event] = [];
     settings.hooks[event] = mergeHookArray(settings.hooks[event], entries);
   }
 
-  // Write settings.json
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
 
-  return { installed: true, scriptsCount, settingsPath };
+  return {
+    installed: true,
+    scriptsCount: new Set(scripts).size,
+    settingsPath,
+    events,
+    skipped,
+    languageLimits: probeLanguageLimits(hooksDir, scripts),
+  };
 }

package/src/installers/integration-installer.js

@@ -1,4 +1,4 @@
-import ora from 'ora';
+import { createSpinner } from '../utils/spinner.js';
 import { copyIntegration } from '../utils/copier.js';
 import {
   writeIntegrationFile,
@@ -32,11 +32,15 @@ export const INTEGRATION_MAPPINGS = {
     target: '.github/copilot-instructions.md'
   },
   antigravity: {
-    source: 'integrations/google-antigravity/INSTRUCTIONS.md',
-    target: 'INSTRUCTIONS.md'
+    source: 'integrations/google-antigravity/AGENTS.md',
+    target: '.agents/AGENTS.md'
   },
   codex: {
-    source: 'integrations/openai-codex/AGENTS.md',
+    // 🔴 Was 'integrations/openai-codex/AGENTS.md'; that directory does not exist.
+    // This map is only reached when generation fails, so a broken entry here is a
+    // fallback that fails exactly when it is needed. Found by walking the map and
+    // stat-ing every source — nothing was checking that these paths resolve.
+    source: 'integrations/codex/AGENTS.md',
     target: 'AGENTS.md'
   },
   'gemini-cli': {
@@ -56,7 +60,7 @@ export const INTEGRATION_MAPPINGS = {
  * @param {Array<string>} config.integrations - List of AI tool names (e.g., ['cursor', 'windsurf'])
  * @param {Object} config.integrationConfigs - Tool-specific configurations
  * @param {Array<string>} config.installedStandards - List of installed standard file names
- * @param {string} config.contentMode - Content mode ('minimal', 'index', 'full')
+ * @param {string} config.contentMode - Content mode ('minimal', 'index'; 'full' retired — XSPEC-357 R7)
  * @param {number} config.level - Adoption level (1-3)
  * @param {string} config.commonLanguage - Language setting ('en', 'zh-tw', 'zh-cn', 'bilingual')
  * @param {string} config.outputLanguage - Output language preference
@@ -95,7 +99,7 @@ export async function installIntegrations(config, projectPath) {
   }
 
   // Start installation spinner
-  const intSpinner = ora(msg.generatingIntegrations).start();
+  const intSpinner = createSpinner(msg.generatingIntegrations).start();
 
   // Track generated files to handle AGENTS.md sharing (codex + opencode)
   const generatedFiles = new Set();
@@ -191,7 +195,7 @@ export async function installIntegrations(config, projectPath) {
  * @param {Object} config - Claude Code configuration
  * @param {Array<string>} config.aiTools - List of selected AI tools
  * @param {Array<string>} config.installedStandards - List of installed standard file names
- * @param {string} config.contentMode - Content mode ('minimal', 'index', 'full')
+ * @param {string} config.contentMode - Content mode ('minimal', 'index'; 'full' retired — XSPEC-357 R7)
  * @param {number} config.level - Adoption level (1-3)
  * @param {string} config.commonLanguage - Language setting ('en', 'zh-tw', 'zh-cn', 'bilingual')
  * @param {string} config.outputLanguage - Output language preference
@@ -220,7 +224,7 @@ export async function generateClaudeMd(config, projectPath) {
     return { path: null, error: null };
   }
 
-  const claudeSpinner = ora(msg.generatingClaudeMd).start();
+  const claudeSpinner = createSpinner(msg.generatingClaudeMd).start();
 
   // Derive categories from installedStandards to avoid referencing non-installed standards
   const categories = installedStandards.length > 0
@@ -281,7 +285,7 @@ export async function generateUniversalAgentsMd(config, integrationResults, proj
   }
 
   const msg = t().commands.init;
-  const spinner = ora(msg.generatingAgentsMd || 'Generating AGENTS.md...').start();
+  const spinner = createSpinner(msg.generatingAgentsMd || 'Generating AGENTS.md...').start();
 
   const outputLanguage = config.outputLanguage || config.commitLanguage ||
     config.standardOptions?.output_language || config.standardOptions?.commit_language ||

package/src/installers/skills-installer.js

@@ -13,7 +13,7 @@
  * @version 1.0.0
  */
 
-import ora from 'ora';
+import { createSpinner } from '../utils/spinner.js';
 import chalk from 'chalk';
 import {
   installSkillsToMultipleAgents,
@@ -115,7 +115,7 @@ function getSkillFiles() {
 export async function installSkills(skillsConfig, projectPath, messages, results) {
   // Modern unified multi-agent installation
   if (skillsConfig.needsInstall && skillsConfig.skillsInstallations?.length > 0) {
-    const skillSpinner = ora(messages.installingSkills).start();
+    const skillSpinner = createSpinner(messages.installingSkills).start();
 
     // Use new unified installer for multi-agent support
     const installResult = await installSkillsToMultipleAgents(
@@ -186,7 +186,7 @@ export async function installSkills(skillsConfig, projectPath, messages, results
  * @returns {Promise<void>}
  */
 async function installSkillsLegacy(skillsConfig, projectPath, messages, results) {
-  const skillSpinner = ora(messages.installingSkills).start();
+  const skillSpinner = createSpinner(messages.installingSkills).start();
 
   const skillFiles = getSkillFiles();
   let successCount = 0;
@@ -255,7 +255,7 @@ export async function installCommands(skillsConfig, projectPath, messages, resul
     return;
   }
 
-  const cmdSpinner = ora(messages.installingCommands || 'Installing slash commands...').start();
+  const cmdSpinner = createSpinner(messages.installingCommands || 'Installing slash commands...').start();
 
   const cmdResult = await installCommandsToMultipleAgents(
     skillsConfig.commandsInstallations,