universal-dev-standards 6.7.5 → 6.9.0

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

@@ -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
@@ -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

package/src/prompts/init.js

@@ -109,7 +109,7 @@ export async function promptAITools(detected = {}) {
           checked: detected.copilot || false
         },
         {
-          name: `Google Antigravity ${chalk.gray('(INSTRUCTIONS.md)')}`,
+          name: `Google Antigravity ${chalk.gray('(.agents/AGENTS.md)')}`,
           value: 'antigravity',
           checked: detected.antigravity || false
         },
@@ -1053,10 +1053,14 @@ export async function promptConfirm(message) {
  *            Best with Skills (which provide real-time guidance).
  * - index:   Summary + MUST/SHOULD task mapping. AI knows when to read which file.
  *            Best balance of context usage and compliance.
- * - full:    All rules embedded. AI has everything in context immediately.
- *            Highest compliance but uses more context space.
  *
- * @returns {Promise<string>} 'full', 'index', or 'minimal'
+ * A third choice, `full` ("all rules embedded, highest compliance, uses more
+ * context"), was removed in XSPEC-357 R7. None of that was true: it shared the
+ * `index` branch in the generator and produced identical bytes. Offering it
+ * asked adopters to trade context budget for compliance in a menu where both
+ * options were the same file. (XSPEC-357 R7)
+ *
+ * @returns {Promise<string>} 'index' or 'minimal'
  */
 export async function promptContentMode() {
   const msg = t().contentMode;
@@ -1075,10 +1079,6 @@ export async function promptContentMode() {
           name: `${chalk.green(msg.labels.index)} ${chalk.gray(`(${t().recommended})`)} - ${msg.choices.index}`,
           value: 'index'
         },
-        {
-          name: `${chalk.blue(msg.labels.full)} - ${msg.choices.full}`,
-          value: 'full'
-        },
         {
           name: `${chalk.gray(msg.labels.minimal)} - ${msg.choices.minimal}`,
           value: 'minimal'
@@ -1159,7 +1159,7 @@ const AI_TOOL_DEFINITIONS = {
   windsurf: { name: 'Windsurf', file: '.windsurfrules' },
   cline: { name: 'Cline', file: '.clinerules' },
   copilot: { name: 'GitHub Copilot', file: '.github/copilot-instructions.md' },
-  antigravity: { name: 'Google Antigravity', file: 'INSTRUCTIONS.md' },
+  antigravity: { name: 'Google Antigravity', file: '.agents/AGENTS.md' },
   codex: { name: 'OpenAI Codex', file: 'AGENTS.md' },
   'gemini-cli': { name: 'Gemini CLI', file: 'GEMINI.md' },
   opencode: { name: 'OpenCode', file: 'AGENTS.md' }
@@ -1286,16 +1286,16 @@ export async function promptContentModeChange(currentMode) {
           name: `${chalk.green(msg.labels.index)} ${chalk.gray(`(${t().recommended})`)} - ${msg.choices.index}`,
           value: 'index'
         },
-        {
-          name: `${chalk.blue(msg.labels.full)} - ${msg.choices.full}`,
-          value: 'full'
-        },
         {
           name: `${chalk.gray(msg.labels.minimal)} - ${msg.choices.minimal}`,
           value: 'minimal'
         }
       ],
-      default: currentMode === 'full' ? 1 : currentMode === 'minimal' ? 2 : 0
+      // A stored `full` lands on `index`, which is the mode it was already
+      // getting. Indices shifted when the middle choice went, so this is
+      // recomputed rather than adjusted — an off-by-one here silently
+      // preselects the wrong mode.
+      default: currentMode === 'minimal' ? 1 : 0
   });
 
   if (mode !== currentMode) {

package/src/reconciler/actual-state-scanner.js

@@ -11,7 +11,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { createHash } from 'crypto';
 import { join, relative } from 'path';
 import { readManifest } from '../core/manifest.js';
-import { computeFileHash, computeIntegrationBlockHash } from '../utils/hasher.js';
+import { computeFileHash, computeIntegrationBlockHash, normalizeLineEndings } from '../utils/hasher.js';
 import { SUPPORTED_AI_TOOLS, UDS_MARKERS } from '../core/constants.js';
 import { getSkillsDirForAgent, getCommandsDirForAgent, getCommandFileExtension } from '../config/ai-agent-paths.js';
 import { getSkillsSourceEntryNames, getAvailableCommandNames } from '../utils/skills-installer.js';
@@ -322,6 +322,13 @@ function shippedCommandNames() {
  * materialising a second array first. The format is the contract; if it changes
  * in one place and not the other every skill reports as changed, which the
  * paired tests in `skill-content-hash.test.js` exist to catch.
+ *
+ * Content is line-ending normalized before hashing (GitHub issue #155): these
+ * are files installed into the adopter's own project, which `git checkout`
+ * may have rewritten to CRLF under `core.autocrlf=true` on Windows even
+ * though the desired side (`computeSkillContentHash`, reading UDS's own
+ * package source) never sees a `\r`. Without matching normalization here,
+ * every skill would report as changed on every Windows `uds update`.
  */
 function hashInstalledSkillDir(dirPath) {
   let entries;
@@ -346,7 +353,7 @@ function hashInstalledSkillDir(dirPath) {
     }
     h.update(name);
     h.update('\0');
-    h.update(content);
+    h.update(normalizeLineEndings(content));
     h.update('\0');
   }
   return `sha256:${h.digest('hex')}`;
@@ -437,12 +444,16 @@ function scanCommands(state, projectPath, manifest) {
       // Content hash of the installed file, for UDS-managed commands only —
       // same reasoning as skills: an adopter's own command has no desired
       // counterpart to compare against. (XSPEC-382 R7)
+      //
+      // Line-ending normalized before hashing (GitHub issue #155), matching
+      // `computeCommandContentHash` on the desired side — the same CRLF
+      // checkout risk `hashInstalledSkillDir` above documents applies here.
       const cmdUdsManaged = shippedCommandNames().has(cmdName);
       let cmdHash = null;
       if (cmdUdsManaged) {
         try {
           cmdHash = `sha256:${createHash('sha256')
-            .update(readFileSync(join(cmdsDir, entry.name), 'utf-8'))
+            .update(normalizeLineEndings(readFileSync(join(cmdsDir, entry.name), 'utf-8')))
             .digest('hex')}`;
         } catch {
           // Unreadable → no hash. A partial answer would claim a match that

package/src/utils/detector.js

@@ -126,7 +126,27 @@ export function detectAITools(projectPath) {
     copilot: existsSync(join(projectPath, '.github', 'copilot-instructions.md')),
     claudeCode: existsSync(join(projectPath, '.claude')) ||
                 existsSync(join(projectPath, 'CLAUDE.md')),
-    antigravity: existsSync(join(projectPath, 'INSTRUCTIONS.md')),
+    // 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')),
+    // 🔴 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
+    // the path table instead of naming tools; nothing else was looking.
+    //
+    // Markers are the ones Roo Code's own docs name, not a guess from the tool name:
+    //   `.roo/rules/`  — "Workspace-wide rules", the current directory-based method
+    //   `.roorules`    — the legacy single-file fallback, still read
+    // (roocodeinc.github.io/Roo-Code/features/custom-instructions, read 2026-09-08)
+    // `.roo` is matched rather than `.roo/rules` because Roo also uses `.roo/skills/`
+    // and `.roo/rules-{mode}/`; the directory is what marks the tool.
+    //
+    // ⚠️ Deliberately NOT `.clinerules`. REGISTRY.json lists it under Roo Code as
+    // legacy backward-compat, and it is also Cline's own marker — detecting on it
+    // would make the two tools indistinguishable.
+    'roo-code': existsSync(join(projectPath, '.roo')) ||
+                existsSync(join(projectPath, '.roorules')),
     codex: hasAgentsMd,
     opencode: hasAgentsMd,
     geminiCli: existsSync(join(projectPath, 'GEMINI.md'))