universal-dev-standards 6.1.0 → 6.2.0

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

@@ -147,11 +147,22 @@ export const AI_AGENT_PATHS = {
   'codex': {
     name: 'OpenAI Codex',
     tier: 'partial',
+    // Verified against the official docs 2026-07-23 (developers.openai.com/codex/skills):
+    // Codex discovers skills in $CWD/.agents/skills, parent directories, $REPO_ROOT/.agents/skills
+    // and $HOME/.agents/skills. Note the plural `.agents/`.
+    //
+    // These were previously '.codex/skills/' and '~/.codex/skills', which Codex never reads —
+    // a directory UDS invented. Skills installed there were invisible, which is why a
+    // behavioural probe against Codex failed while Codex itself was behaving correctly
+    // (see integrations/verification/codex/2026-07-23.md).
     skills: {
-      project: '.codex/skills/',
-      user: join(homedir(), '.codex', 'skills')
+      project: '.agents/skills/',
+      user: join(homedir(), '.agents', 'skills')
     },
     commands: null, // Uses system commands
+    // NOT verified. The official skills docs describe `agents/openai.yaml` as a file *inside*
+    // a skill directory, not a separate top-level agents location. Left as-is rather than
+    // guessed at: an unverified path fails silently, which is the failure mode being fixed above.
     agents: {
       project: '.codex/agents/',
       user: join(homedir(), '.codex', 'agents')
@@ -241,16 +252,27 @@ export const AI_AGENT_PATHS = {
   'antigravity': {
     name: 'Google Antigravity',
     tier: 'minimal',
-    skills: {
-      project: '.agent/skills/',
-      user: join(homedir(), '.gemini', 'antigravity', 'skills')
-    },
+    // 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.
+    //
+    // 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.
+    //
+    // 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,
     commands: null,
     agents: null,
     workflows: null,
     supportsMarketplace: false,
     fallbackSkillsPath: null,
-    supportsSkills: true, // Skills since Nov 2025
+    supportsSkills: true, // The tool does support skills; only our path for it is unverified.
     supportsTask: false,
     supportsAgents: false
   }
@@ -313,6 +335,24 @@ export function getCommandsDirForAgent(agent, level = 'project', projectPath = n
   return null;
 }
 
+/**
+ * Get the on-disk file extension used for an agent's slash commands.
+ *
+ * The command *name* (`commit`) and the installed *file* (`commit.toml` for
+ * Gemini CLI, `commit.md` for everyone else) are not the same string. Any code
+ * that maps one to the other must go through here — a hard-coded `.md` strip
+ * silently drops every Gemini command on the floor, and because the mismatch
+ * produces a well-formed name that simply never matches, nothing errors.
+ * (XSPEC-343 R2: 30 of machine-setup's 86 proposed deletions were exactly this.)
+ *
+ * @param {string} agent - Agent identifier
+ * @returns {string} Extension including the leading dot
+ */
+export function getCommandFileExtension(agent) {
+  const config = AI_AGENT_PATHS[agent];
+  return config?.commandFormat === 'toml' ? '.toml' : '.md';
+}
+
 /**
  * Get all agents that support skills installation
  * @returns {string[]} Array of agent identifiers

package/src/core/constants.js

@@ -523,4 +523,64 @@ export default {
   doesToolSupport,
   getToolFormat,
   getToolFileName
-};
+};
+
+/**
+ * `manifest.integrations` has been written in two shapes by two code paths:
+ * tool keys (`claude-code`) and file paths (`CLAUDE.md`, or even absolute).
+ * Three consumers read it with two different assumptions —
+ * desired-state-calculator expects tool keys, integration-uninstaller expects
+ * file names — so normalising to one shape fixes one and breaks the other.
+ *
+ * These two resolvers let every consumer accept either shape. Measured
+ * 2026-07-30: 20 of 21 adopter repos stored file names. (XSPEC-343 R1)
+ */
+
+/** Entry (tool key OR file path) → tool key, or null. */
+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, '/');
+  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;
+  }
+  return null;
+}
+
+/** Entry (tool key OR file path) → repo-relative integration file, or null. */
+export function resolveIntegrationFile(entry) {
+  const key = resolveToolKey(entry);
+  return key ? SUPPORTED_AI_TOOLS[key].file : null;
+}
+
+/**
+ * How the flat keys in `manifest.options` bind to registry option categories.
+ *
+ * The manifest stores selections flat — `{ workflow: 'github-flow',
+ * test_levels: [...] }` — while the registry nests them under a standard id and
+ * a category key, and the two names are not always the same word (`test_levels`
+ * vs `test_level`). The installer knew this mapping inline; the reconciler's
+ * desired-state calculator instead iterated `manifest.options` as if it were
+ * keyed by *standard id*, looked up a standard called `workflow`, found nothing,
+ * and skipped. It produced an empty desired option set for every adopter repo,
+ * so every installed option file diffed as "no longer in desired state" —
+ * including the ones the manifest explicitly selected. (XSPEC-343 R2)
+ *
+ * Keys with no entry here (`display_language`, `release_mode`, `coverage_model`)
+ * are behaviour settings that install no file.
+ */
+export const MANIFEST_OPTION_BINDINGS = [
+  { manifestKeys: ['workflow'], standardId: 'git-workflow', categoryKey: 'workflow' },
+  { manifestKeys: ['merge_strategy'], standardId: 'git-workflow', categoryKey: 'merge_strategy' },
+  { manifestKeys: ['output_language', 'commit_language'], standardId: 'commit-message', categoryKey: 'output_language' },
+  { manifestKeys: ['test_levels'], standardId: 'testing', categoryKey: 'test_level' }
+];
+
+/**
+ * Option files are installed flat, not nested by standard/category.
+ * (`installers/standards-installer.js` copies into `.standards/options`.)
+ */
+export const OPTIONS_INSTALL_DIR = '.standards/options';

package/src/core/manifest.js

@@ -389,6 +389,18 @@ function migrateToV340(manifest) {
   };
 }
 
+// 這裡曾有一個 v3.5.0 遷移，把 `integrations` 正規化為工具鍵。**已撤回。**
+//
+// 撤回的理由，是窮舉讀取端之後才看見的：這個欄位有**兩個陣營**，而且大致均衡。
+//   期待檔名  ：hasher.js（{source:i,target:i}）、check.js ×6（join(projectPath, int)、
+//               filter(i => i !== relativePath)）
+//   期待工具鍵：desired-state-calculator、manifest-migrator、update.js:856（getToolFilePath）
+// 把資料正規化成任何一種，就是修好一邊、弄壞另一邊。
+// 全套 3,240 個測試在正規化之後仍然全綠——那只代表**檔名陣營那幾條路徑沒有覆蓋**，不是安全。
+//
+// 正解是不動資料，讓每個讀取端經 `resolveToolKey` / `resolveIntegrationFile` 容忍兩種形狀。
+// 真要正規化，得排在**所有**讀取端都容錯之後，作為獨立一步。（XSPEC-343 R1）
+
 /**
  * Convert a standards array from legacy path format to registry ID format.
  * Entries that already look like IDs (no "/" or ".") are kept as-is.
@@ -601,4 +613,48 @@ export function areSkillsInstalled(manifest) {
  */
 export function areCommandsInstalled(manifest) {
   return manifest.commands?.installed || false;
+}
+
+/**
+ * Placeholder stored in `skills.names` when skills come from the Claude Code
+ * plugin marketplace rather than being copied into the project.
+ */
+export const MARKETPLACE_NAMES_SENTINEL = 'all-via-plugin';
+
+/**
+ * Merge the names actually installed by a run into a manifest name list.
+ *
+ * `skills.names` / `commands.names` used to be written by `init` and by no other
+ * code path, so they froze on the day a project was set up: machine-setup's said
+ * 32 skills across five UDS upgrades while the shipped set grew to 55. Nothing
+ * errored — a name list that is merely *incomplete* reads exactly like a complete
+ * one, and the reconciler read the gap as "these 40 are no longer wanted".
+ * (XSPEC-343 R1/R2)
+ *
+ * Every code path that installs skills or commands must call this. It lives here
+ * rather than in a command module because there are 18 such call sites across
+ * update.js and config.js, and a private copy per module is how the writers drift
+ * apart again.
+ *
+ * It only ever adds. A name recorded by an older UDS version that no longer ships
+ * (machine-setup still lists `methodology-system`, plus five non-skill directories
+ * an old deny-list bug misfiled as skills) stays in the list. Pruning would need
+ * to know the name is absent for *every* agent, and over-reporting is harmless
+ * now that the reconciler derives desired state from the shipped set instead.
+ *
+ * @param {string[]} existing - Current manifest list
+ * @param {Object} installResult - Result from installSkills/CommandsToMultipleAgents
+ * @returns {string[]} Sorted union of existing and newly installed names
+ */
+export function mergeInstalledNames(existing, installResult) {
+  const merged = new Set(existing || []);
+  // Marketplace installs record a sentinel instead of real names; leave it alone.
+  if (merged.has(MARKETPLACE_NAMES_SENTINEL)) return [...merged];
+
+  for (const agentResult of installResult?.installations || []) {
+    for (const name of agentResult?.installed || []) {
+      merged.add(name);
+    }
+  }
+  return [...merged].sort();
 }

package/src/flow/flow-parser.js

@@ -4,7 +4,7 @@
  * 解析 .flow.yaml 內容為 Flow 物件，包含 schema 驗證和預設值填充。
  */
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 const DEFAULT_CONFIG = {
   enforcement: 'suggest',

package/src/flow/gate-loader.js

@@ -4,7 +4,7 @@
  * 載入和解析 .gate.yaml 閘門定義。
  */
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 /**
  * 從 YAML 字串載入 gate 定義。

package/src/i18n/messages.js

@@ -742,8 +742,8 @@ export const messages = {
         adoptionStatus: 'Adoption Status:',
         installed: 'Installed',
         // Update info
-        updateAvailable: '⚠ Update available: {current} → {latest}',
-        runUpdate: 'Run `uds update` to update.',
+        updateAvailable: '⚠ Your installed standards are behind the latest release: {current} → {latest}',
+        runUpdate: 'Update in two steps —  (1) npm update -g universal-dev-standards   (2) uds update',
         // File integrity
         fileIntegrity: 'File Integrity:',
         hashNotAvailable: 'ℹ Hash information not available (legacy manifest).',
@@ -831,6 +831,8 @@ export const messages = {
         fileNotFound: 'File not found',
         couldNotRead: 'Could not read file',
         standardsIndexPresent: 'Standards index present',
+        standardsIndexCount: 'Index declares {count} standards (matches manifest)',
+        standardsIndexCountMismatch: 'Index declares {declared} standards but the manifest has {actual}',
         standardsReferenced: '{count}/{total} standards referenced',
         missingStandardsList: 'Missing: {list}',
         usingMinimalMode: 'Using minimal mode (no standards index)',
@@ -1974,8 +1976,8 @@ export const messages = {
         adoptionStatus: '採用狀態：',
         installed: '已安裝',
         // Update info
-        updateAvailable: '⚠ 有可用更新：{current} → {latest}',
-        runUpdate: '執行 `uds update` 進行更新。',
+        updateAvailable: '⚠ 你安裝的標準落後最新版：{current} → {latest}',
+        runUpdate: '兩步驟更新 —（1）npm update -g universal-dev-standards （2）uds update',
         // File integrity
         fileIntegrity: '檔案完整性：',
         hashNotAvailable: 'ℹ 無法取得 hash 資訊（舊版 manifest）。',
@@ -2063,6 +2065,8 @@ export const messages = {
         fileNotFound: '找不到檔案',
         couldNotRead: '無法讀取檔案',
         standardsIndexPresent: '標準索引存在',
+        standardsIndexCount: '索引宣告 {count} 條標準（與 manifest 一致）',
+        standardsIndexCountMismatch: '索引宣告 {declared} 條標準，manifest 實際有 {actual} 條',
         standardsReferenced: '{count}/{total} 項標準已參考',
         missingStandardsList: '缺少：{list}',
         usingMinimalMode: '使用最小模式（無標準索引）',
@@ -3221,8 +3225,8 @@ export const messages = {
         adoptionStatus: '采用状态：',
         installed: '已安装',
         // Update info
-        updateAvailable: '⚠ 有可用更新：{current} → {latest}',
-        runUpdate: '执行 `uds update` 进行更新。',
+        updateAvailable: '⚠ 你安装的标准落后最新版：{current} → {latest}',
+        runUpdate: '两步更新 —（1）npm update -g universal-dev-standards （2）uds update',
         // File integrity
         fileIntegrity: '文件完整性：',
         hashNotAvailable: 'ℹ 哈希信息不可用（旧版 manifest）。',
@@ -3310,6 +3314,8 @@ export const messages = {
         fileNotFound: '文件未找到',
         couldNotRead: '无法读取文件',
         standardsIndexPresent: '标准索引存在',
+        standardsIndexCount: '索引声明 {count} 条标准（与 manifest 一致）',
+        standardsIndexCountMismatch: '索引声明 {declared} 条标准，manifest 实际有 {actual} 条',
         standardsReferenced: '已引用 {count}/{total} 项标准',
         missingStandardsList: '缺失：{list}',
         usingMinimalMode: '使用最小模式（无标准索引）',

package/src/installers/standards-installer.js

@@ -10,6 +10,7 @@ import {
 import { copyStandard } from '../utils/copier.js';
 import { t } from '../i18n/messages.js';
 import { computeFileHash } from '../utils/hasher.js';
+import { MANIFEST_OPTION_BINDINGS } from '../core/constants.js';
 
 // Extension file mappings
 export const EXTENSION_MAPPINGS = {
@@ -89,28 +90,17 @@ export async function installStandards(config, projectPath) {
       }
     }
 
-    // Copy selected options for this standard
+    // Copy selected options for this standard.
+    // The manifest-key → (standard, category) mapping lives in MANIFEST_OPTION_BINDINGS
+    // so the reconciler computes the same desired set this loop installs. It used to
+    // be spelled out inline here and guessed at incorrectly there. (XSPEC-343 R2)
     if (std.options) {
       for (const targetFormat of formatsToUse) {
-        // Git workflow options
-        if (std.id === 'git-workflow') {
-          if (config.standardOptions.workflow) {
-            const copied = await copyOptionFiles(std, 'workflow', config.standardOptions.workflow, targetFormat);
-            results.standards.push(...copied);
-          }
-          if (config.standardOptions.merge_strategy) {
-            const copied = await copyOptionFiles(std, 'merge_strategy', config.standardOptions.merge_strategy, targetFormat);
-            results.standards.push(...copied);
-          }
-        }
-        // Commit message options
-        if (std.id === 'commit-message' && (config.standardOptions.output_language || config.standardOptions.commit_language)) {
-          const copied = await copyOptionFiles(std, 'output_language', config.standardOptions.output_language || config.standardOptions.commit_language, targetFormat);
-          results.standards.push(...copied);
-        }
-        // Testing options
-        if (std.id === 'testing' && config.standardOptions.test_levels) {
-          const copied = await copyOptionFiles(std, 'test_level', config.standardOptions.test_levels, targetFormat);
+        for (const binding of MANIFEST_OPTION_BINDINGS) {
+          if (binding.standardId !== std.id) continue;
+          const key = binding.manifestKeys.find(k => config.standardOptions?.[k] != null);
+          if (!key) continue;
+          const copied = await copyOptionFiles(std, binding.categoryKey, config.standardOptions[key], targetFormat);
           results.standards.push(...copied);
         }
       }

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

@@ -12,7 +12,16 @@ import { join, relative } from 'path';
 import { readManifest } from '../core/manifest.js';
 import { computeFileHash, computeIntegrationBlockHash } from '../utils/hasher.js';
 import { SUPPORTED_AI_TOOLS, UDS_MARKERS } from '../core/constants.js';
-import { getSkillsDirForAgent, getCommandsDirForAgent } from '../config/ai-agent-paths.js';
+import { getSkillsDirForAgent, getCommandsDirForAgent, getCommandFileExtension } from '../config/ai-agent-paths.js';
+import { getSkillsSourceEntryNames, getAvailableCommandNames } from '../utils/skills-installer.js';
+
+/**
+ * Files UDS writes into a skills/commands directory for its own bookkeeping.
+ * They are not skills or commands and must never be diffed as such — the
+ * scanner used to report `.manifest.json` as a stray command, which made the
+ * reconciler propose deleting its own installation record. (XSPEC-343 R2)
+ */
+const INSTALLER_BOOKKEEPING_FILES = new Set(['.manifest.json']);
 
 /**
  * Scan the actual state of UDS artifacts on disk.
@@ -241,6 +250,57 @@ function scanIntegrations(state, projectPath) {
   }
 }
 
+/**
+ * Read a directory, tolerating the read itself failing (race, permissions).
+ *
+ * Deliberately narrow: only `readdirSync` is wrapped. The scan loops used to sit
+ * inside the same `catch {}`, so any programming error in the loop body became
+ * "this agent has no skills/commands" — an empty actual state indistinguishable
+ * from a genuinely empty directory, which downstream reads as "nothing to delete,
+ * install everything".
+ */
+function readDirEntries(dirPath) {
+  try {
+    return readdirSync(dirPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+let _sourceEntries = null;
+let _shippedCommands = null;
+
+/** Directory names UDS ships under `skills/`, cached per process. */
+function sourceEntryNames() {
+  if (_sourceEntries === null) _sourceEntries = getSkillsSourceEntryNames();
+  return _sourceEntries;
+}
+
+/** Command names UDS ships, cached per process. */
+function shippedCommandNames() {
+  if (_shippedCommands === null) _shippedCommands = new Set(getAvailableCommandNames());
+  return _shippedCommands;
+}
+
+/**
+ * Did UDS put this skill directory here?
+ *
+ * Two positive signals, either is enough:
+ *   1. a directory of the same name exists in UDS's own `skills/` tree — this
+ *      also covers the non-skill siblings (`_shared`, `agents`, …) that an older
+ *      CLI copied in by mistake, so they stay cleanable;
+ *   2. `manifest.skillHashes` records a file under it — authoritative when
+ *      present, though in practice it is sparse (dev-platform: 2 entries for 78
+ *      installed skills), which is exactly why signal 1 has to carry the weight.
+ *
+ * Anything else is the adopter's own, and is warned about rather than deleted.
+ */
+function isUdsProvenance(skillName, manifest, agent, level) {
+  if (sourceEntryNames().has(skillName)) return true;
+  const prefix = `${agent}/${level}/${skillName}/`;
+  return Object.keys(manifest?.skillHashes || {}).some((k) => k.startsWith(prefix));
+}
+
 /**
  * Scan skill installations.
  */
@@ -252,27 +312,32 @@ function scanSkills(state, projectPath, manifest) {
     const skillsDir = getSkillsDirForAgent(agent, level, projectPath);
     if (!skillsDir || !existsSync(skillsDir)) continue;
 
-    try {
-      const entries = readdirSync(skillsDir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-        const skillName = entry.name;
-        const key = `skill:${agent}:${level}:${skillName}`;
-        const relPath = level === 'project'
-          ? getRelativePath(projectPath, join(skillsDir, skillName))
-          : join(skillsDir, skillName);
-
-        state.skills.set(key, {
-          relativePath: relPath,
-          hash: null,  // Directory-level hashes tracked in manifest.skillHashes
-          size: null,
-          category: 'skill',
-          sourcePath: null,
-          metadata: { agent, level, skillName, scanned: true }
-        });
-      }
-    } catch {
-      // Ignore read errors
+    for (const entry of readDirEntries(skillsDir)) {
+      if (!entry.isDirectory()) continue;
+      const skillName = entry.name;
+      const key = `skill:${agent}:${level}:${skillName}`;
+      const relPath = level === 'project'
+        ? getRelativePath(projectPath, join(skillsDir, skillName))
+        : join(skillsDir, skillName);
+
+      state.skills.set(key, {
+        relativePath: relPath,
+        hash: null,  // Directory-level hashes tracked in manifest.skillHashes
+        size: null,
+        category: 'skill',
+        sourcePath: null,
+        metadata: {
+          agent,
+          level,
+          skillName,
+          scanned: true,
+          // Whether UDS is the thing that put this directory here. Everything in
+          // the skills folder used to be assumed UDS-managed, so a plan for a repo
+          // with hand-written skills proposed deleting them: dev-platform's would
+          // have removed fourteen. (XSPEC-343 R2)
+          udsManaged: isUdsProvenance(skillName, manifest, agent, level)
+        }
+      });
     }
   }
 }
@@ -288,27 +353,37 @@ function scanCommands(state, projectPath, manifest) {
     const cmdsDir = getCommandsDirForAgent(agent, level, projectPath);
     if (!cmdsDir || !existsSync(cmdsDir)) continue;
 
-    try {
-      const entries = readdirSync(cmdsDir, { withFileTypes: true });
-      for (const entry of entries) {
-        // Commands can be files (.md) or directories
-        const cmdName = entry.name.replace(/\.md$/, '');
-        const key = `command:${agent}:${level}:${cmdName}`;
-        const relPath = level === 'project'
-          ? getRelativePath(projectPath, join(cmdsDir, entry.name))
-          : join(cmdsDir, entry.name);
-
-        state.commands.set(key, {
-          relativePath: relPath,
-          hash: null,
-          size: null,
-          category: 'command',
-          sourcePath: null,
-          metadata: { agent, level, commandName: cmdName, scanned: true }
-        });
-      }
-    } catch {
-      // Ignore read errors
+    const ext = getCommandFileExtension(agent);
+
+    for (const entry of readDirEntries(cmdsDir)) {
+      if (INSTALLER_BOOKKEEPING_FILES.has(entry.name)) continue;
+
+      // Commands are files named `<name><ext>` (or, for some agents, directories).
+      // Stripping a hard-coded `.md` left every Gemini command as `commit.toml`,
+      // which never matches the desired key `commit`, so all of them were
+      // proposed for deletion.
+      const cmdName = entry.name.endsWith(ext)
+        ? entry.name.slice(0, -ext.length)
+        : entry.name;
+      const key = `command:${agent}:${level}:${cmdName}`;
+      const relPath = level === 'project'
+        ? getRelativePath(projectPath, join(cmdsDir, entry.name))
+        : join(cmdsDir, entry.name);
+
+      state.commands.set(key, {
+        relativePath: relPath,
+        hash: null,
+        size: null,
+        category: 'command',
+        sourcePath: null,
+        metadata: {
+          agent,
+          level,
+          commandName: cmdName,
+          scanned: true,
+          udsManaged: shippedCommandNames().has(cmdName)
+        }
+      });
     }
   }
 }