universal-dev-standards 6.8.0 → 6.10.0

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. */

package/src/core/manifest.js

@@ -55,6 +55,62 @@ export const DEFAULT_MANIFEST = {
   integrationBlockHashes: {}
 };
 
+/**
+ * Content modes an adopter may choose.
+ *
+ * `full` was retired in favour of `index` (XSPEC-357 R7). It was never a third
+ * behaviour: the only place the mode is read is a single `=== 'minimal'` test
+ * in `generateComplianceInstructions`, so `full` and `index` took the same
+ * branch and produced byte-identical files — 24 of 24 tool × language
+ * combinations, against a control confirming the comparison does detect a real
+ * difference (`full` vs `minimal` differed in all 24). Meanwhile the manifest
+ * schema accepted it, `--content-mode` offered it, the init prompt listed it as
+ * a distinct trade-off ("highest compliance, uses more context"), and every
+ * `partial`-tier tool was assigned it automatically. Adopters were choosing
+ * between two labels for one behaviour, and the label promised a difference
+ * that did not exist.
+ */
+export const SUPPORTED_CONTENT_MODES = ['minimal', 'index'];
+
+/**
+ * Retired content modes and what they now resolve to.
+ *
+ * The rewrite changes no adopter's output, because the two modes already
+ * generated the same bytes — which is what makes this breaking change cheap
+ * enough to do at all. Kept as a map rather than special-cased at each call
+ * site so the next retirement has somewhere to go.
+ */
+export const RETIRED_CONTENT_MODES = { full: 'index' };
+
+/**
+ * Resolve a content mode, migrating retired ones and flagging unknown ones.
+ *
+ * An unknown value resolves to `fallback` and is reported in `unrecognized`, so
+ * the caller can warn. The original intent was to throw — a *silent* fallback
+ * turns `--content-mode indx` into a normal run with nothing saying so — and
+ * that remains the goal for 7.0.0. It does not throw in 6.x because 6.8.0
+ * accepted unknown values and generated the `index` output, and
+ * `core/versioning.md` requires a deprecation warning in a MINOR release before
+ * behaviour that used to work starts failing. The warning is what removes the
+ * silence; the error is the MAJOR-version step.
+ *
+ * @param {string|undefined} mode - Requested mode
+ * @param {string} fallback - Mode to use when nothing was requested, or when the value is unknown
+ * @returns {{mode: string, migratedFrom: string|null, unrecognized: string|null}}
+ */
+export function normalizeContentMode(mode, fallback = 'index') {
+  if (mode === undefined || mode === null || mode === '') {
+    return { mode: fallback, migratedFrom: null, unrecognized: null };
+  }
+  if (SUPPORTED_CONTENT_MODES.includes(mode)) {
+    return { mode, migratedFrom: null, unrecognized: null };
+  }
+  if (Object.prototype.hasOwnProperty.call(RETIRED_CONTENT_MODES, mode)) {
+    return { mode: RETIRED_CONTENT_MODES[mode], migratedFrom: mode, unrecognized: null };
+  }
+  return { mode: fallback, migratedFrom: null, unrecognized: mode };
+}
+
 /**
  * Validation schema for manifest
  */
@@ -63,10 +119,125 @@ const MANIFEST_SCHEMA = {
   properties: {
     version: { type: 'string', pattern: '^\\d+\\.\\d+\\.\\d+$' },
     format: { type: 'string', enum: ['ai', 'human', 'both'] },
-    contentMode: { type: 'string', enum: ['minimal', 'index', 'full'] }
+    contentMode: { type: 'string', enum: SUPPORTED_CONTENT_MODES }
   }
 };
 
+/**
+ * Provenance — the record of which files UDS itself wrote. (XSPEC-384 R1)
+ *
+ * Ownership is a question about *origin*, and origin is something you record at
+ * the moment you write, not something you infer afterwards from another table.
+ * `fileHashes` was doing the inferring: absence from it was read as "not ours",
+ * although a manifest loses entries through version migrations, hand edits,
+ * merge conflicts, and older CLI bugs. The tool then picked the destructive
+ * branch for the case it could not actually distinguish.
+ *
+ * Two properties matter and neither is shared with `fileHashes`:
+ *
+ *  - It is append-only. `fileHashes` is current state and gets rewritten every
+ *    run; provenance is history. If both were written and pruned together,
+ *    provenance would add nothing — it would just be a second copy that fails
+ *    the same way at the same moment.
+ *  - It is keyed by the path actually written, taken from the copy result,
+ *    not by re-deriving the path from the source name. The re-derivation is
+ *    wrong for nested option files (`options/<category>/<name>.ai.yaml` is
+ *    flattened to `options/<name>.ai.yaml`), so a path-math-based record would
+ *    claim ownership of files that do not exist while disowning ones that do.
+ *
+ * An entry is removed only when UDS deliberately deletes the file — deleting it
+ * is how we relinquish the claim, so that a file a user later creates under the
+ * same name is not silently inherited.
+ */
+export const PROVENANCE_SCHEMA_VERSION = 1;
+
+/**
+ * Valid writers, used so a typo becomes an error rather than an unrecognised
+ * provenance record that reads as "not ours".
+ */
+export const PROVENANCE_WRITERS = ['init', 'update', 'config', 'sync'];
+
+/**
+ * Record that UDS wrote a file.
+ * @param {Object} manifest - Manifest (not mutated)
+ * @param {string} relPath - Path relative to project root
+ * @param {string} writer - One of PROVENANCE_WRITERS
+ * @returns {Object} Updated manifest
+ */
+export function recordFileProvenance(manifest, relPath, writer) {
+  if (!relPath) return manifest;
+  const normalized = relPath.replace(/\\/g, '/');
+  const at = new Date().toISOString();
+  const existing = manifest?.provenance?.files?.[normalized];
+  return {
+    ...manifest,
+    provenance: {
+      schema: PROVENANCE_SCHEMA_VERSION,
+      ...(manifest?.provenance || {}),
+      files: {
+        ...(manifest?.provenance?.files || {}),
+        [normalized]: {
+          firstWrittenBy: existing?.firstWrittenBy || writer,
+          firstWrittenAt: existing?.firstWrittenAt || at,
+          lastWrittenBy: writer,
+          lastWrittenAt: at
+        }
+      }
+    }
+  };
+}
+
+/**
+ * Drop a provenance record, relinquishing UDS's claim on a path.
+ * @param {Object} manifest - Manifest (not mutated)
+ * @param {string} relPath - Path relative to project root
+ * @returns {Object} Updated manifest
+ */
+export function forgetFileProvenance(manifest, relPath) {
+  const normalized = (relPath || '').replace(/\\/g, '/');
+  const files = { ...(manifest?.provenance?.files || {}) };
+  delete files[normalized];
+  return {
+    ...manifest,
+    provenance: {
+      schema: PROVENANCE_SCHEMA_VERSION,
+      ...(manifest?.provenance || {}),
+      files
+    }
+  };
+}
+
+/**
+ * Mark provenance as a complete account of what UDS owns.
+ *
+ * Called at the end of a run that wrote the full installed set. Until this has
+ * happened at least once, a file with no provenance record is `unknown` rather
+ * than `foreign`, because the absence of a record proves nothing yet.
+ *
+ * @param {Object} manifest - Manifest (not mutated)
+ * @returns {Object} Updated manifest
+ */
+export function establishProvenance(manifest) {
+  return {
+    ...manifest,
+    provenance: {
+      schema: PROVENANCE_SCHEMA_VERSION,
+      files: {},
+      ...(manifest?.provenance || {}),
+      establishedAt: manifest?.provenance?.establishedAt || new Date().toISOString()
+    }
+  };
+}
+
+/**
+ * Whether provenance can be trusted as a complete list of UDS-owned files.
+ * @param {Object} manifest - Manifest
+ * @returns {boolean}
+ */
+export function isProvenanceEstablished(manifest) {
+  return !!manifest?.provenance?.establishedAt;
+}
+
 /**
  * Get manifest file path for a project
  * @param {string} projectPath - Project root path
@@ -354,10 +525,25 @@ function migrateToV320(manifest) {
   return {
     ...manifest,
     version: '3.2.0',
-    contentMode: manifest.contentMode || 'index'
+    contentMode: migrateRetiredContentMode(manifest.contentMode)
   };
 }
 
+/**
+ * Rewrite a retired content mode to its replacement, leaving anything else
+ * alone. Unlike `normalizeContentMode` this never throws: it runs while reading
+ * a manifest, and refusing to load a project because of one stale string would
+ * be a worse outcome than loading it and letting `validateManifest` report.
+ * @param {string|undefined} mode
+ * @returns {string}
+ */
+function migrateRetiredContentMode(mode) {
+  if (mode && Object.prototype.hasOwnProperty.call(RETIRED_CONTENT_MODES, mode)) {
+    return RETIRED_CONTENT_MODES[mode];
+  }
+  return mode || 'index';
+}
+
 /**
  * Migration to version 3.3.0
  * @param {Object} manifest - V3.2.x manifest
@@ -502,11 +688,23 @@ function ensureRequiredFields(manifest) {
     ...manifest,
     options,
     standards,
-    contentMode: manifest.contentMode || 'index',
+    // Rewrites a stored `full` to `index`. This is the migration path for
+    // existing adopters and it runs on every read, so a manifest written by an
+    // older CLI is corrected the first time a newer one touches it — without
+    // changing a single byte of what that project's AI tool files receive.
+    contentMode: migrateRetiredContentMode(manifest.contentMode),
     fileHashes: normalizedHashes,
     skillHashes: manifest.skillHashes || {},
     commandHashes: manifest.commandHashes || {},
     integrationBlockHashes: manifest.integrationBlockHashes || {},
+    // Present but deliberately NOT established. Filling in `establishedAt`
+    // here would declare "these records are complete" about a manifest that
+    // has never had a provenance-aware run, which is the one claim that turns
+    // every pre-existing file into `foreign` — and `foreign` is the state the
+    // deletion path acts on. Only a completed run may establish it.
+    // A fresh object per call: a shared default would be one mutable record
+    // handed to every manifest in the process. (XSPEC-384 R1)
+    provenance: manifest.provenance || { schema: PROVENANCE_SCHEMA_VERSION, files: {} },
   };
 }
 

package/src/core/paths.js

@@ -149,8 +149,8 @@ export class PathResolver {
       'copilot': 'copilot-instructions.md',
       'aider': '.aider.conf.yml',
       'opencode': 'AGENTS.md',
-      'roo': 'ROO.md',
-      'antigravity': 'INSTRUCTIONS.md'
+      'roo-code': '.roo/rules/uds-standards.md',
+      'antigravity': '.agents/AGENTS.md'
     };
 
     const targetFile = toolTargets[tool] || fileName;