universal-dev-standards 6.8.0 → 6.9.0

package/src/commands/update.js

@@ -2,11 +2,11 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { select, confirm as inquirerConfirm, checkbox, Separator } from '@inquirer/prompts';
 import { execSync } from 'child_process';
-import { existsSync, readFileSync, unlinkSync } from 'fs';
-import { join, basename } from 'path';
-import { readManifest, writeManifest, copyStandard, isInitialized } from '../utils/copier.js';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { join, basename, dirname, relative } from 'path';
+import { readManifest, writeManifest, copyStandard, isInitialized, getRepoRoot } from '../utils/copier.js';
 import { getRepositoryInfo, getAllStandards, getStandardSource } from '../utils/registry.js';
-import { computeFileHash, scanForUntrackedFiles, refreshIntegrationBlockHashes } from '../utils/hasher.js';
+import { computeFileHash, planStandardsRemovals, refreshIntegrationBlockHashes } from '../utils/hasher.js';
 import {
   writeIntegrationFile,
   getToolFilePath,
@@ -42,6 +42,7 @@ import {
   getCommandsDirForAgent
 } from '../config/ai-agent-paths.js';
 import { getMarketplaceSkillsInfo } from '../utils/github.js';
+import { detectAITools } from '../utils/detector.js';
 import {
   promptSkillsInstallLocation,
   promptCommandsInstallation
@@ -56,7 +57,110 @@ import {
 import { restoreSingleFile } from './check.js';
 import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
 import { resolveIntegrationFile } from '../core/constants.js';
-import { mergeInstalledNames } from '../core/manifest.js';
+import {
+  mergeInstalledNames,
+  recordFileProvenance,
+  forgetFileProvenance,
+  establishProvenance,
+  isProvenanceEstablished
+} from '../core/manifest.js';
+
+/**
+ * How aggressive `uds update` is about deleting standards it no longer ships.
+ *
+ * XSPEC-384 §4 leaves the staging strategy for R2 undecided, so this is the
+ * most conservative of the three options on the table and it lives in one named
+ * place rather than being spread through the deletion path. Changing this
+ * constant is the whole change of default; the alternatives are:
+ *
+ *   'report-only'  list what would go, delete nothing without --prune  (current)
+ *   'ask'          list, and prompt in interactive sessions only
+ *   'auto'         delete as part of a normal update
+ *
+ * It starts at 'report-only' because the change is adopter-visible in the
+ * dangerous direction: files that survive today start disappearing. A default
+ * that deletes must not arrive in a patch release, and must not arrive at all
+ * before someone decides it should.
+ */
+export const PRUNE_POLICY = 'report-only';
+
+/**
+ * Decide whether this run is allowed to delete.
+ *
+ * `--prune` is deliberately its own flag rather than a use of `--yes`. `--yes`
+ * means "don't ask me about the thing I already asked for"; it is set in CI and
+ * in scripts, and letting it also authorise deletion would enable the
+ * destructive path silently in exactly the unattended environments that cannot
+ * notice it. Non-interactive runs therefore never delete unless --prune is
+ * explicit. (XSPEC-384 R3)
+ *
+ * @param {Object} plan - Result of planStandardsRemovals
+ * @param {Object} options - Command options
+ * @returns {boolean}
+ */
+export function shouldPrune(plan, options = {}) {
+  if (plan.remove.length === 0) return false;
+  if (options.prune) return true;
+  return PRUNE_POLICY === 'auto';
+}
+
+/**
+ * Print the removal plan, including its denominator. (XSPEC-384 R3)
+ *
+ * The counts are not decoration. A report that lists only the files it intends
+ * to touch is bit-for-bit identical to a report from a scan that only *saw*
+ * those files — which is the failure the previous code shipped for months,
+ * silently, because nothing ever printed how many files it had considered.
+ *
+ * @param {Object} plan - Result of planStandardsRemovals
+ * @param {boolean} provenanceWasEstablished - Whether ownership was already known
+ * @param {boolean} willDelete - Whether this run is going to act on the plan
+ */
+export function reportRemovalPlan(plan, provenanceWasEstablished, willDelete = false) {
+  if (plan.scanned === 0) return;
+
+  console.log();
+  console.log(chalk.gray(
+    `  .standards/ examined: ${plan.scanned} file(s) — ` +
+    `${plan.census.udsOwned} written by UDS, ` +
+    `${plan.census.foreign} not ours, ` +
+    `${plan.census.unknown} ownership unknown, ` +
+    `${plan.excluded.length} excluded`
+  ));
+  for (const { path: p, reason } of plan.excluded) {
+    console.log(chalk.gray(`    excluded ${p} (${reason})`));
+  }
+
+  if (!provenanceWasEstablished) {
+    console.log(chalk.gray(
+      '    first run with ownership tracking: files installed before this ' +
+      'release cannot be attributed yet, so none will be removed.'
+    ));
+  }
+
+  if (plan.remove.length === 0) {
+    if (plan.census.foreign > 0 || plan.census.unknown > 0) {
+      console.log(chalk.gray(
+        `    kept ${plan.census.foreign + plan.census.unknown} file(s) UDS did not write`
+      ));
+    }
+    return;
+  }
+
+  console.log();
+  console.log(chalk.yellow(
+    `  ${plan.remove.length} file(s) are no longer shipped by UDS` +
+    (willDelete ? ' and will be removed:' : ':')
+  ));
+  for (const { path: p, reason } of plan.remove) {
+    console.log(chalk.yellow(`    - ${p}  (${reason})`));
+  }
+  console.log(chalk.gray(
+    willDelete
+      ? '    Removing now (--prune). Files UDS did not write are never touched.'
+      : '    Not deleted. Re-run with --prune to remove them.'
+  ));
+}
 
 /**
  * Determine the correct target directory for a standard file.
@@ -546,6 +650,21 @@ export async function updateCommand(options) {
     errors: []
   };
 
+  // Paths UDS actually wrote this run, taken from the copy result rather than
+  // recomputed from the source name. Recomputing is how `fileHashes` ended up
+  // with five `.standards/options/<name>.ai.yaml` entries for files that live
+  // at `.standards/options/<category>/<name>.ai.yaml`; a provenance record
+  // built the same way would claim files that do not exist and disown ones
+  // that do. (XSPEC-384 R1)
+  const writtenPaths = [];
+  const recordWritten = (result) => {
+    if (!result?.success || !result.data) return;
+    const abs = typeof result.data === 'string' ? result.data : null;
+    if (!abs) return;
+    const rel = relative(projectPath, abs).replace(/\\/g, '/');
+    if (rel && !rel.startsWith('..')) writtenPaths.push(rel);
+  };
+
   // Update standards
   const updateFormat = manifest.format || 'ai';
   const allStdsUpdate = getAllStandards();
@@ -561,6 +680,7 @@ export async function updateCommand(options) {
     const result = await copyStandard(sourcePath, getStandardTargetDir(sourcePath), projectPath);
     if (result.success) {
       results.updated.push(std);
+      recordWritten(result);
     } else {
       results.errors.push(`${std}: ${result.error}`);
     }
@@ -572,6 +692,7 @@ export async function updateCommand(options) {
     const result = await copyStandard(ext, '.standards', projectPath);
     if (result.success) {
       results.updated.push(ext);
+      recordWritten(result);
     } else {
       results.errors.push(`${ext}: ${result.error}`);
     }
@@ -601,6 +722,7 @@ export async function updateCommand(options) {
         if (result.success) {
           manifest.standards.push(ns.source);
           results.updated.push(ns.source);
+          recordWritten(result);
           newCount++;
         } else {
           results.errors.push(`${ns.source}: ${result.error}`);
@@ -751,6 +873,20 @@ export async function updateCommand(options) {
     manifest.fileHashes = {};
   }
 
+  // The set of `.standards/` files the *current* registry says should exist.
+  //
+  // Built by accumulating inside the loops that already resolve each entry,
+  // rather than by a second function that re-derives the same paths. A second
+  // derivation is a second copy, and the two would answer "where does this
+  // standard live" differently the moment either is edited — which is the
+  // failure mode XSPEC-384 is about, not a shape to reproduce. (XSPEC-384 R2)
+  const desiredStandardsFiles = new Set();
+
+  // Standards whose ID no longer resolves against the registry. Collected here
+  // instead of being silently `continue`d, because "skipped" and "deleted
+  // upstream" were previously indistinguishable — issue #165. (XSPEC-384 R2)
+  const unresolvedStandardIds = [];
+
   // Update hashes for standards (handles both ID format and legacy path format)
   const hashFormat = manifest.format || 'ai';
   const allStdsHash = getAllStandards();
@@ -759,7 +895,13 @@ export async function updateCommand(options) {
     let resolvedPath = std;
     if (!std.includes('/') && !std.includes('.')) {
       const entry = allStdsHash.find(r => r.id === std);
-      if (!entry) continue; // Skip unrecognized IDs (e.g. stale AI tool names)
+      if (!entry) {
+        // Unrecognized ID: either a standard removed from the registry, or a
+        // stale AI tool name an old CLI wrote into `standards`. Either way it
+        // is no longer a thing we ship, so it must not enter the desired set.
+        unresolvedStandardIds.push(std);
+        continue;
+      }
       const src = getStandardSource(entry, hashFormat);
       if (src) resolvedPath = src;
     }
@@ -767,6 +909,10 @@ export async function updateCommand(options) {
     const relativePath = (resolvedPath.includes('options/')
       ? join('.standards', 'options', fileName)
       : join('.standards', fileName)).replace(/\\/g, '/');
+    // Added before the hash check: a file that exists but failed to hash is
+    // still wanted. Nominating it for deletion because hashing failed would
+    // turn a transient read error into data loss.
+    desiredStandardsFiles.add(relativePath);
     const fullPath = join(projectPath, relativePath);
     const hashInfo = computeFileHash(fullPath);
     if (hashInfo) {
@@ -779,6 +925,7 @@ export async function updateCommand(options) {
     if (typeof ext !== 'string') continue;
     const fileName = basename(ext);
     const relativePath = join('.standards', fileName).replace(/\\/g, '/');
+    desiredStandardsFiles.add(relativePath);
     const fullPath = join(projectPath, relativePath);
     const hashInfo = computeFileHash(fullPath);
     if (hashInfo) {
@@ -795,21 +942,63 @@ export async function updateCommand(options) {
     }
   }
 
-  // Clean up orphan files in .standards/ that are no longer tracked
-  // This handles files renamed or removed between versions
-  const orphanFiles = scanForUntrackedFiles(projectPath, manifest);
-  const standardsOrphans = orphanFiles.filter(f => f.startsWith('.standards/'));
-  if (standardsOrphans.length > 0) {
-    for (const orphan of standardsOrphans) {
+  // Record what UDS wrote this run, then decide what (if anything) may go.
+  // (XSPEC-384 R1/R2/R3)
+  const provenanceWasEstablished = isProvenanceEstablished(manifest);
+  let provenanceCarrier = manifest;
+  for (const written of [...writtenPaths, ...results.integrations]) {
+    provenanceCarrier = recordFileProvenance(provenanceCarrier, written, 'update');
+  }
+  manifest.provenance = provenanceCarrier.provenance;
+
+  // Drop `standards` entries the registry no longer knows about. Previously
+  // these were `continue`d in three separate loops and left in the manifest
+  // forever, so `upstream.version` advanced to "latest" while the manifest
+  // still listed standards that had not existed for releases. (issue #165)
+  if (unresolvedStandardIds.length > 0) {
+    manifest.standards = manifest.standards.filter(s => !unresolvedStandardIds.includes(s));
+    console.log();
+    console.log(chalk.yellow(
+      `⚠ ${unresolvedStandardIds.length} manifest entr${unresolvedStandardIds.length === 1 ? 'y is' : 'ies are'} no longer in the registry and ${unresolvedStandardIds.length === 1 ? 'was' : 'were'} dropped:`
+    ));
+    for (const id of unresolvedStandardIds) {
+      console.log(chalk.gray(`    - ${id}`));
+    }
+  }
+
+  const removalPlan = planStandardsRemovals(projectPath, manifest, desiredStandardsFiles);
+  // Decide before reporting, so the report states what this run will actually
+  // do. Reporting first meant printing "Not deleted. Re-run with --prune" on a
+  // run that was about to delete — a message contradicting the very action it
+  // preceded, which is worse than no message.
+  const mayPrune = shouldPrune(removalPlan, options);
+  reportRemovalPlan(removalPlan, provenanceWasEstablished, mayPrune);
+
+  if (mayPrune && removalPlan.remove.length > 0) {
+    for (const { path: orphan } of removalPlan.remove) {
       try {
         unlinkSync(join(projectPath, orphan));
         results.updated.push(`removed: ${orphan}`);
+        delete manifest.fileHashes[orphan];
+        // Deleting the file is how we give up the claim on that path, so a
+        // file the user later creates under the same name is not inherited.
+        manifest.provenance = forgetFileProvenance(manifest, orphan).provenance;
       } catch {
         // Ignore removal errors
       }
     }
   }
 
+  // Provenance is only a complete account of what we own once a run has
+  // written the whole installed set. Until then every unrecorded file is
+  // `unknown` rather than `foreign`, and nothing gets deleted on the strength
+  // of an absent record. Establishing it here — after the writes, not before —
+  // is what makes the first upgrade conservative by construction rather than
+  // by a flag someone has to remember. (XSPEC-384 §4)
+  if (results.errors.length === 0) {
+    manifest.provenance = establishProvenance(manifest).provenance;
+  }
+
   // Migrate display_language: if manifest options is missing display_language,
   // attempt to backfill from ~/.udsrc ui.language so the project honours the
   // language the user already configured globally.
@@ -1366,11 +1555,58 @@ export async function updateCommand(options) {
 
   console.log();
 
+  // 錯誤訊息單一出口閘門：問過才寫，而且從不覆寫。
+  await offerErrorExitGate(projectPath, options);
+
   // Exit explicitly to prevent hanging.
   // T11: a partial update exits non-zero so CI / scripts can detect the failure.
   process.exit(updateIncomplete ? 1 : 0);
 }
 
+/**
+ * 提供錯誤訊息單一出口閘門——**顯示它是什麼、問過、才寫，而且絕不覆寫既有檔案。**
+ *
+ * 🔴 為什麼不自動寫：`uds` 是別人裝進自己 repo 的工具。未經同意往陌生人的專案
+ *    寫一支可執行腳本，比它要修的那個問題更糟——那會變成信任問題，而不是 bug。
+ *    採用者說不要，我們就不寫，而且下次 `uds check` 只會再提一次，不會偷偷放進去。
+ *
+ * ⚠️ 已存在就直接跳過，連問都不問：那個檔案裡的 CONFIG 是採用者自己填的，
+ *    我們沒有立場拿範本蓋掉它。要更新內容是另一件事，不在這裡做。
+ */
+async function offerErrorExitGate(projectPath, options) {
+  const dest = join(projectPath, 'scripts', 'check-error-exit.mjs');
+  if (existsSync(dest)) return;                              // 他們自己的檔案
+  if (!existsSync(join(projectPath, 'src'))) return;         // 沒有原始碼就沒有這個問題
+
+  const src = join(getRepoRoot(), 'templates', 'gates', 'check-error-exit.mjs');
+  if (!existsSync(src)) return;                              // 範本沒出貨——沉默，不要假裝提供了
+
+  console.log(chalk.bold('  錯誤訊息單一出口閘門'));
+  console.log(chalk.gray('    防的是：每個呼叫端各自把錯誤回應拼成給人看的字串。'));
+  console.log(chalk.gray('    第一處是實作，第二處開始就會各寫各的，而畫面上只剩一句 Bad Request。'));
+  console.log(chalk.gray(`    要寫入：scripts/check-error-exit.mjs（純 Node、零相依、${Math.round(readFileSync(src, 'utf-8').length / 1024)}KB）`));
+  console.log(chalk.gray('    寫入後它會 exit 2 直到你填好 CONFIG——那是刻意的，'));
+  console.log(chalk.gray('    一支在新 repo 裡靜靜回綠的閘門跟一支沒裝的無從分辨。'));
+  console.log();
+
+  const ok = await confirmOrFail({
+    message: '要把這道閘門寫進 scripts/check-error-exit.mjs 嗎？',
+    defaultValue: false,   // 🔴 預設不寫。沉默不是同意。
+    options
+  });
+  if (!ok) {
+    console.log(chalk.gray('  跳過。`uds check` 之後會再提醒，但不會自己寫進去。'));
+    console.log();
+    return;
+  }
+
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, readFileSync(src, 'utf-8'), 'utf-8');
+  console.log(chalk.green('  ✓ 已寫入 scripts/check-error-exit.mjs'));
+  console.log(chalk.gray('    下一步：填好檔頭的 CONFIG，然後把它接進你的 CI 或 pre-commit。'));
+  console.log();
+}
+
 /**
  * Regenerate integration files for all configured AI tools
  * Reusable core logic that can be called from both updateIntegrationsOnly and configureCommand
@@ -1845,7 +2081,35 @@ async function updateSkillsOnly(projectPath, manifest, options) {
       // Convert legacy format to new format
       const legacyLocation = manifest.skills.location;
       if (legacyLocation === 'user' || legacyLocation === 'project') {
-        skillsInstallations.push({ agent: 'claude-code', level: legacyLocation });
+        // 🔴 A legacy manifest records a LOCATION, never a tool — and this used to
+        // fill the gap with `claude-code`, unconditionally. For everyone who ran the
+        // old `uds init -y` in a codex or opencode repo, that guess is wrong and
+        // self-perpetuating: the fix to `init.js` would never reach them, because
+        // update would keep re-installing to `.claude/skills/` on the strength of a
+        // tool name nobody ever recorded. (XSPEC-408 §18.3 — Codex does not read
+        // that directory; measured, two arms, 2026-09-08.)
+        //
+        // So re-derive from what is actually detected in the repo, and keep
+        // `claude-code` only as the fallback for when nothing is detected — which is
+        // exactly the case the old line was written for.
+        let detected = {};
+        try {
+          detected = detectAITools(projectPath) || {};
+        } catch {
+          // Detection failing puts us in the "we do not know" case, which is exactly
+          // what the old unconditional `claude-code` line was for. Never let a probe
+          // for extra information break the update that would have worked without it.
+          detected = {};
+        }
+        const detectedSkillsTools = Object.entries(detected)
+          .filter(([, present]) => present)
+          .map(([key]) => (key === 'claudeCode' ? 'claude-code' : key === 'geminiCli' ? 'gemini-cli' : key))
+          .filter(agent => {
+            const config = getAgentConfig(agent);
+            return Boolean(config?.supportsSkills && config?.skills);
+          });
+        const agents = detectedSkillsTools.length > 0 ? detectedSkillsTools : ['claude-code'];
+        for (const agent of agents) skillsInstallations.push({ agent, level: legacyLocation });
       } else if (legacyLocation === 'marketplace') {
         console.log(chalk.yellow(msg.skillsViaMarketplace || 'Skills installed via Marketplace'));
         console.log(chalk.gray(`  ${msg.updateViaMarketplace || 'Update through Plugin Marketplace'}`));
@@ -1913,8 +2177,16 @@ async function updateSkillsOnly(projectPath, manifest, options) {
   }).join(', ');
 
   if (result.totalErrors === 0) {
+    // 🔴 `{count}` is worded "AI tools" in every locale, and this passed
+    // `totalInstalled` — the number of skill FILES written, summed across targets.
+    // A two-tool update of 55 skills printed "Updated Skills for 165 AI tools".
+    // It was invisible while this branch only ran from the interactive flow; the
+    // fix to `init.js` makes it the common path, so it stops being invisible.
     spinner.succeed((msg.skillsUpdated || 'Updated Skills in {count} locations: {locations}')
-      .replace('{count}', result.totalInstalled)
+      // Counted from the same list that builds `locations`, so the number and the
+      // names can never disagree — and it does not depend on the shape of the
+      // installer's return value.
+      .replace('{count}', fileBasedInstallations.length)
       .replace('{locations}', locations));
   } else {
     spinner.warn((msg.skillsUpdatedWithErrors || 'Updated Skills with {errors} errors')

package/src/compilers/claude-code-compiler.js

@@ -33,9 +33,12 @@ export class ClaudeCodeCompiler extends BaseCompiler {
         hooks[trigger] = [];
       }
 
+      // Claude Code dispatches on `type`; an entry without one is skipped
+      // silently. Measured 2026-09-08 with both shapes in the same event of the
+      // same session: the object ran, the bare string did not.
       hooks[trigger].push({
         matcher,
-        hooks: [`node ${hook_script}`],
+        hooks: [{ type: 'command', command: `node ${hook_script}` }],
       });
     }
 

package/src/config/ai-agent-paths.js

@@ -139,7 +139,19 @@ export const AI_AGENT_PATHS = {
       user: join(homedir(), '.roo', 'workflows')
     },
     supportsMarketplace: false,
-    fallbackSkillsPath: '.claude/skills/',
+    // 🔴 Was '.claude/skills/', with no provenance. Roo Code's docs ENUMERATE where it
+    // looks for skills — `.roo/skills/`, `.agents/skills/`, and their `~` twins — and
+    // `.claude/skills/` is not among them. An enumerated discovery list that omits a
+    // path is a statement, not silence (same shape as the Codex list that this field
+    // was falsified against by measurement).
+    //
+    // ⚠️ Docs only, 2026-09-08: NOT measured, because there is no Roo Code CLI on this
+    // machine. Acting on it anyway because the asymmetry is one-sided — wrong here
+    // means skills land in `.roo/skills/`, which the docs confirm is read; leaving it
+    // meant `uds init` routed Roo Code to Claude's marketplace and installed **zero**
+    // skills, which is what it actually did until this change.
+    // (roocodeinc.github.io/Roo-Code/features/skills)
+    fallbackSkillsPath: null,
     supportsSkills: true,
     supportsTask: true,
     supportsAgents: true
@@ -169,7 +181,14 @@ export const AI_AGENT_PATHS = {
     },
     workflows: null,
     supportsMarketplace: false,
-    fallbackSkillsPath: '.claude/skills/',
+    // 🔴 Was '.claude/skills/'. MEASURED FALSE 2026-09-08 (XSPEC-408 §18.3): two probe
+    // arms differing only in install path. At `.agents/skills` Codex reported "Skill
+    // descriptions were shortened to fit the 2% skills context budget — Codex can
+    // still see every skill", 18,096 input tokens. At `.claude/skills` it said
+    // nothing, 15,235. The discovery list documented above never included that
+    // directory; this field asserted otherwise with no provenance, and `check.js`
+    // printed it to adopters as "Can use fallback".
+    fallbackSkillsPath: null,
     supportsSkills: true,
     supportsTask: false,
     supportsAgents: true
@@ -251,28 +270,54 @@ export const AI_AGENT_PATHS = {
   },
   'antigravity': {
     name: 'Google Antigravity',
-    tier: 'minimal',
-    // Skills install path is UNVERIFIED against a real Antigravity CLI, so it is null:
-    // `supportsSkills && skills` is the install guard everywhere (init.js, init-flow.js,
-    // update.js, config.js), and a null `skills` makes it decline rather than write to a
-    // path the tool may never read.
+    // Raised from 'minimal' 2026-09-08. It was minimal because UDS installed
+    // nothing for it — the tier was describing our own gap, not the tool. It now
+    // gets 55 skills and an instruction file, the same as the other 'partial'
+    // tools, and passes all six of that tier's rules.
+    tier: 'partial',
+    // Skills path CONFIRMED 2026-09-08, three independent ways:
+    //   1. The agy 1.0.14 binary carries the literal template
+    //      `{workspace}/.agents/skills/{skill_name}/SKILL.md`.
+    //   2. The guide shipped with the tool
+    //      (~/.gemini/antigravity-cli/builtin/skills/antigravity_guide/references/ide.md)
+    //      says `<project-root>/.agents/` holds "project-specific rules, custom skills,
+    //      and plugins".
+    //   3. A live two-arm run: a skill at `.agents/skills/` was listed back with its
+    //      description verbatim; a decoy at `.agent/skills/` was not listed at all.
+    //
+    // 🔴 BOTH candidates previously recorded here were wrong — the official-plugin path
+    // and `.agent/skills/` (singular). Neither had been tested; declining to install was
+    // the right call for six months, and the answer came from the tool's own binary, not
+    // from either document.
     //
-    // Two candidates conflict, and neither has been tested:
-    //   a) ~/.gemini/antigravity-cli/plugins/<name>/skills/  -- official plugin docs
-    //   b) .agent/skills/ + ~/.gemini/antigravity/skills     -- UDS's own 2026-02 spec,
-    //      written while Gemini CLI was still the product; Antigravity replaced it on
-    //      2026-06-18, so (b) inherits an assumption that may no longer hold.
+    // 🔴 PRECONDITION the adopter must meet: agy only discovers `.agents/` when the
+    // directory is a registered Antigravity project (~/.gemini/projects.json). Measured:
+    // the same probe repo returned only the builtin skill before `agy --new-project` and
+    // both skills after. Installing here is correct, but a user who never opens the
+    // project in Antigravity will see nothing — that is the tool's condition, not ours.
     //
-    // Installing to the wrong path fails SILENTLY -- the user sees a successful init and
-    // an assistant that never picks the skills up. Declining is the safer default until
-    // one candidate is confirmed. Tracked as XSPEC-355 OQ6.
-    skills: null,
+    // No `user` path: the binary has exactly one skills template and it is
+    // workspace-scoped. A user-level path would be invented, which is how the two wrong
+    // candidates above got written down in the first place.
+    skills: {
+      project: '.agents/skills/'
+    },
+    // Shown to the adopter after a successful install. A field rather than a
+    // special case for this tool: the next tool with a precondition fills it in
+    // instead of adding a branch. Without it the condition lives only in a spec,
+    // and the adopter — who reads neither — sees a successful install and an
+    // assistant that picked nothing up.
+    installNote:
+      'Antigravity only discovers .agents/ once the directory is a registered '
+      + 'Antigravity project. Open it in the IDE, or run `agy --new-project` here '
+      + 'once. Measured 2026-09-08: the same repo reported only the built-in skill '
+      + 'before that and all of them after.',
     commands: null,
     agents: null,
     workflows: null,
     supportsMarketplace: false,
     fallbackSkillsPath: null,
-    supportsSkills: true, // The tool does support skills; only our path for it is unverified.
+    supportsSkills: true,
     supportsTask: false,
     supportsAgents: false
   }

package/src/core/constants.js

@@ -94,16 +94,25 @@ export const SUPPORTED_AI_TOOLS = {
     category: 'secondary',
     supports: ['skills']
   },
-  'roo': {
-    name: 'Roo',
-    file: 'ROO.md',
+  // 🔴 Key was 'roo' and the file was 'ROO.md'. Every other module calls this tool
+  // `roo-code` (`ai-agent-paths.js`, `REGISTRY.json`, `agent-adapter.js`,
+  // `agents-installer.js`), so every lookup here MISSED — and the miss was silent:
+  // `getToolFileName()` ends in `return \`${tool}.md\``, so a real `uds init` in a Roo
+  // Code repo wrote its instructions to `roo-code.md` in the repo root. Roo Code's
+  // docs name `.roo/rules/`, `.roorules`, and `AGENTS.md`; `roo-code.md` is read by
+  // nothing, and `ROO.md` was never written by anything either.
+  // File value matches REGISTRY.json's `instructionFile` for this agent.
+  // (roocodeinc.github.io/Roo-Code/features/custom-instructions, read 2026-09-08)
+  'roo-code': {
+    name: 'Roo Code',
+    file: '.roo/rules/uds-standards.md',
     format: 'markdown',
     category: 'secondary',
     supports: ['skills', 'workflows']
   },
   'antigravity': {
     name: 'Antigravity',
-    file: 'INSTRUCTIONS.md',
+    file: '.agents/AGENTS.md',
     format: 'markdown',
     category: 'secondary',
     supports: ['skills', 'workflows']
@@ -122,7 +131,12 @@ export const SUPPORTED_AI_TOOLS = {
  */
 export const LEGACY_TOOL_MAPPINGS = {
   'codex': 'opencode',
-  'copilot': 'github-copilot'
+  'copilot': 'github-copilot',
+  // Maps the OLD key to the CORRECT one, never the reverse — an alias pointing at
+  // the wrong name would make the wrong name authoritative. No manifest in any of
+  // the five adopting repos records 'roo' (checked 2026-09-08); this exists for
+  // manifests written before the rename.
+  'roo': 'roo-code'
 };
 
 /**
@@ -141,10 +155,13 @@ export const FILE_EXTENSIONS = {
 /**
  * Content modes for integration files
  */
+// `FULL: 'full'` was removed here (XSPEC-357 R7). It never produced different
+// output from INDEX — the generator's only test on the mode is `=== 'minimal'`
+// — so it was a second name for one behaviour, offered to adopters as a
+// distinct choice. See SUPPORTED_CONTENT_MODES in core/manifest.js.
 export const CONTENT_MODES = {
   MINIMAL: 'minimal',    // Reference-only content
-  INDEX: 'index',        // Standard index with descriptions
-  FULL: 'full'          // Full standard content embedded
+  INDEX: 'index'         // Standard index with descriptions + compliance instructions
 };
 
 /**
@@ -541,13 +558,27 @@ export function resolveToolKey(entry) {
   if (typeof entry !== 'string' || entry.length === 0) return null;
   if (SUPPORTED_AI_TOOLS[entry]) return entry;
   const norm = entry.replace(/\\/g, '/');
+
+  // Exact or path-suffix only. A bare basename match would let `MY-CLAUDE.md`
+  // or `CLAUDE.md.bak` pass as the managed integration file.
+  //
+  // 🔴 Two passes, and the order matters. Antigravity's file is
+  // `.agents/AGENTS.md` while OpenCode's is `AGENTS.md`, so a single pass
+  // resolved `.agents/AGENTS.md` to OpenCode — whichever tool happened to be
+  // declared first won a path the other had spelled out in full. An exactly
+  // declared path must beat another tool's suffix, and among suffixes the
+  // longest (most specific) one wins.
+  for (const [key, cfg] of Object.entries(SUPPORTED_AI_TOOLS)) {
+    if (cfg?.file && norm === cfg.file) return key;
+  }
+  let best = null;
   for (const [key, cfg] of Object.entries(SUPPORTED_AI_TOOLS)) {
     if (!cfg?.file) continue;
-    // Exact or path-suffix only. A bare basename match would let `MY-CLAUDE.md`
-    // or `CLAUDE.md.bak` pass as the managed integration file.
-    if (norm === cfg.file || norm.endsWith(`/${cfg.file}`)) return key;
+    if (norm.endsWith(`/${cfg.file}`) && (!best || cfg.file.length > best.len)) {
+      best = { key, len: cfg.file.length };
+    }
   }
-  return null;
+  return best ? best.key : null;
 }
 
 /** Entry (tool key OR file path) → repo-relative integration file, or null. */