universal-dev-standards 6.10.0 → 6.11.0

package/src/i18n/messages.js

@@ -840,7 +840,7 @@ export const messages = {
         refSyncStatus: 'Reference Sync Status:',
         noRefsFound: 'No standard references found',
         refsNotInManifest: 'References not in manifest:',
-        standardsNotReferenced: 'Standards not referenced (optional):',
+        standardsNotReferenced: 'Standards with no "Reference:"/"參考:" line in this file (optional):',
         refsInSync: '{path}: references in sync ({count} refs)',
         noIntegrationRefs: 'No integration files with standard references found.',
         runSyncRefs: 'Run `uds update --sync-refs` to fix reference issues.',
@@ -2080,7 +2080,7 @@ export const messages = {
         refSyncStatus: '參考同步狀態：',
         noRefsFound: '找不到標準參考',
         refsNotInManifest: '未在 manifest 中的參考：',
-        standardsNotReferenced: '未參考的標準（選用）：',
+        standardsNotReferenced: '本檔案中沒有「Reference:」或「參考:」行提及的標準（選用）：',
         refsInSync: '{path}：參考已同步（{count} 個參考）',
         noIntegrationRefs: '找不到有標準參考的整合檔案。',
         runSyncRefs: '執行 `uds update --sync-refs` 修復參考問題。',
@@ -3332,7 +3332,7 @@ export const messages = {
         refSyncStatus: '参考同步状态：',
         noRefsFound: '未找到标准引用',
         refsNotInManifest: 'manifest 中无引用：',
-        standardsNotReferenced: '未引用的标准（可选）：',
+        standardsNotReferenced: '本文件中没有"Reference:"或"參考:"行提及的标准（可选）：',
         refsInSync: '{path}：引用已同步（{count} 个引用）',
         noIntegrationRefs: '未找到包含标准引用的集成文件。',
         runSyncRefs: '执行 `uds update --sync-refs` 修复引用问题。',

package/src/installers/integration-installer.js

@@ -3,7 +3,7 @@ import { copyIntegration } from '../utils/copier.js';
 import {
   writeIntegrationFile,
   integrationFileExists,
-  getToolFilePath,
+  resolveIntegrationTargetFile,
   writeAgentsMdSummary,
   resolveContentModeForTool
 } from '../utils/integration-generator.js';
@@ -106,7 +106,9 @@ export async function installIntegrations(config, projectPath) {
 
   for (const tool of integrations) {
     // Check if this file was already generated (for AGENTS.md sharing)
-    const targetFile = getToolFilePath(tool);
+    // XSPEC-418 R2: honors config.integrationTargets (set from --claude-target at
+    // init time) rather than always assuming each tool's default file.
+    const targetFile = resolveIntegrationTargetFile(tool, { integrationTargets: config.integrationTargets });
     if (generatedFiles.has(targetFile)) {
       // Skip - file already generated by another tool (e.g., codex generated AGENTS.md, skip opencode)
       continue;
@@ -129,7 +131,9 @@ export async function installIntegrations(config, projectPath) {
       contentMode: resolved.contentMode,
       level: resolved.level ?? level,
       // Pass output_language for dynamic commit standards generation
-      outputLanguage
+      outputLanguage,
+      // XSPEC-418 R2: forwarded so writeIntegrationFile resolves the actual target.
+      integrationTargets: config.integrationTargets
     };
 
     // Use dynamic generator
@@ -218,9 +222,10 @@ export async function generateClaudeMd(config, projectPath) {
 
   const msg = t().commands.init;
 
-  // Check if Claude Code is selected and CLAUDE.md doesn't exist
+  // Check if Claude Code is selected and its target file doesn't already exist
+  // XSPEC-418 R2: the target may be CLAUDE.local.md, not CLAUDE.md.
   const claudeCodeSelected = aiTools.includes('claude-code');
-  if (!claudeCodeSelected || integrationFileExists('claude-code', projectPath)) {
+  if (!claudeCodeSelected || integrationFileExists('claude-code', projectPath, { integrationTargets: config.integrationTargets })) {
     return { path: null, error: null };
   }
 
@@ -245,7 +250,9 @@ export async function generateClaudeMd(config, projectPath) {
     contentMode: claudeResolved.contentMode,
     level: claudeResolved.level ?? level,
     // Pass output_language for dynamic commit standards generation
-    outputLanguage
+    outputLanguage,
+    // XSPEC-418 R2
+    integrationTargets: config.integrationTargets
   };
 
   const result = writeIntegrationFile('claude-code', claudeConfig, projectPath);

package/src/installers/manifest-installer.js

@@ -31,6 +31,10 @@ export function writeFinalManifest(config, results, projectPath) {
     extensions: results.extensions || [],
     integrations: results.integrations || [],
     integrationConfigs: results.manifestIntegrationConfigs || {},
+    // XSPEC-418 R2: only ever present when --claude-target local was chosen.
+    // Omitted entirely otherwise so a manifest with no override is byte-for-byte
+    // what it was before this feature existed (AC-5).
+    ...(config.integrationTargets ? { integrationTargets: config.integrationTargets } : {}),
     options: {
       display_language: config.displayLanguage || 'en',
       workflow: config.standardOptions?.workflow || null,

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

@@ -13,6 +13,7 @@ import { join, relative } from 'path';
 import { readManifest } from '../core/manifest.js';
 import { computeFileHash, computeIntegrationBlockHash, normalizeLineEndings } from '../utils/hasher.js';
 import { SUPPORTED_AI_TOOLS, UDS_MARKERS } from '../core/constants.js';
+import { locateMarkerBlock, AmbiguousMarkerError } from '../utils/marker-locator.js';
 import { getSkillsDirForAgent, getCommandsDirForAgent, getCommandFileExtension } from '../config/ai-agent-paths.js';
 import { getSkillsSourceEntryNames, getAvailableCommandNames } from '../utils/skills-installer.js';
 
@@ -230,7 +231,21 @@ function scanIntegrations(state, projectPath) {
     const filePath = join(projectPath, toolConfig.file);
     if (!existsSync(filePath)) continue;
 
-    const blockHash = computeIntegrationBlockHash(filePath);
+    // XSPEC adopter-report Q5: this scan walks every configured tool's file
+    // in one pass to build a full picture of the project — one file with an
+    // ambiguous marker pair must not abort the whole scan. `uds check`'s
+    // dedicated block-integrity pass is what surfaces the ambiguity to the
+    // user explicitly, with line numbers; this scan just records "unknown".
+    let blockHash;
+    try {
+      blockHash = computeIntegrationBlockHash(filePath);
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        blockHash = null;
+      } else {
+        throw error;
+      }
+    }
     const fileHash = computeFileHash(filePath);
 
     state.integrations.set(toolConfig.file, {
@@ -543,7 +558,19 @@ function hasUDSMarkers(filePath, format) {
   try {
     const content = readFileSync(filePath, 'utf-8');
     const markers = UDS_MARKERS[format] || UDS_MARKERS.markdown;
-    return content.includes(markers.start) && content.includes(markers.end);
+    // XSPEC adopter-report Q5: `.includes()` matched the marker text
+    // anywhere in the file, including inside a sentence that merely mentions
+    // it — locateMarkerBlock requires a standalone, non-fenced line. An
+    // ambiguous file (two real marker lines) still "has UDS markers" for
+    // this boolean's purpose, so that is also true, not an error here.
+    try {
+      return locateMarkerBlock(content, markers) !== null;
+    } catch (error) {
+      if (error instanceof AmbiguousMarkerError) {
+        return true;
+      }
+      throw error;
+    }
   } catch {
     return false;
   }

package/src/reconciler/desired-state-calculator.js

@@ -15,8 +15,15 @@ import {
   MANIFEST_OPTION_BINDINGS,
   OPTIONS_INSTALL_DIR
 } from '../core/constants.js';
+import {
+  resolveIntegrationTargetFile,
+  buildToolIntegrationConfig,
+  generateIntegrationContent,
+  extractMarkedContent
+} from '../utils/integration-generator.js';
 import { PathResolver } from '../core/paths.js';
 import { computeFileHash } from '../utils/hasher.js';
+import { createHash } from 'crypto';
 import {
   getSkillsDirForAgent,
   getCommandsDirForAgent,
@@ -261,6 +268,37 @@ function calculateExtensions(state, manifest) {
   }
 }
 
+/**
+ * Compute the block hash generation would produce for this tool right now,
+ * using the same builder (`buildToolIntegrationConfig`) and generator
+ * (`generateIntegrationContent`) `--apply`/`uds update` themselves use.
+ *
+ * Hashed the same way `computeIntegrationBlockHash` (hasher.js) hashes an
+ * actual on-disk file — extract the marker block, trim, sha256 — so the two
+ * are directly comparable. Never throws: generation can fail for reasons
+ * outside this module's control (an incomplete/mocked registry, a tool this
+ * process cannot resolve, etc.), and the correct response to "cannot compute
+ * an expected hash" is `null` — diffIntegrations already knows how to treat
+ * that the same as before this fix (always migrate_block), not to crash the
+ * whole state calculation over one tool.
+ *
+ * @param {Object} manifest
+ * @param {string} toolName
+ * @param {string} format
+ * @returns {string|null}
+ */
+function computeExpectedIntegrationBlockHash(manifest, toolName, format) {
+  try {
+    const config = { ...buildToolIntegrationConfig(manifest, toolName), format: manifest.format || 'ai' };
+    const generated = generateIntegrationContent({ ...config, tool: toolName });
+    const { content: blockContent } = extractMarkedContent(generated, format);
+    if (!blockContent) return null;
+    return `sha256:${createHash('sha256').update(blockContent).digest('hex')}`;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Calculate expected integration files.
  * For integrations we track the UDS marker block, not the entire file.
@@ -281,11 +319,22 @@ function calculateIntegrations(state, manifest) {
     const toolConfig = toolName ? SUPPORTED_AI_TOOLS[toolName] : null;
     if (!toolConfig) continue;
 
-    const relativePath = toolConfig.file;
+    // XSPEC-418 R2/R3: the desired path is the tool's ACTUAL target, not always
+    // its default file — a local-target claude-code install's desired state
+    // must say CLAUDE.local.md, or `--apply`/`--plan` (and their orphan
+    // detection) would treat that file as unmanaged and CLAUDE.md as desired.
+    const relativePath = resolveIntegrationTargetFile(toolName, manifest) || toolConfig.file;
 
     state.integrations.set(relativePath, {
       relativePath,
-      hash: null,  // Integration hashes are computed after generation
+      // XSPEC adopter-report Q6: this used to be a hardcoded `null` ("hashes
+      // are computed after generation"), which is why diffIntegrations could
+      // never tell "content already matches" from "content differs" and
+      // unconditionally produced migrate_block — `--plan` never converged,
+      // even immediately after `--apply`. Actually generating the content
+      // ahead of time (the same generation `--apply` itself runs) gives a
+      // real hash to compare against the actual file's block hash.
+      hash: computeExpectedIntegrationBlockHash(manifest, toolName, toolConfig.format),
       size: null,
       category: 'integration',
       sourcePath: null,  // Generated, not copied from source

package/src/reconciler/diff-engine.js

@@ -272,18 +272,34 @@ function diffIntegrations(desiredMap, actualMap, actions, warnings, summary, for
           }
         });
         summary.migrate_block++;
+      } else if (desiredEntry.hash && actualEntry.hash && desiredEntry.hash === actualEntry.hash) {
+        // XSPEC adopter-report Q6: the block on disk already hashes the same
+        // as what generation would produce right now — nothing to do. Before
+        // this, every migrate_block fired unconditionally ("we always update
+        // integrations since content is generated dynamically"), so `--plan`
+        // reported `Migrate Block: N` forever, even immediately after
+        // `--apply` on an unchanged project. `desiredEntry.hash` is computed
+        // by desired-state-calculator.js actually generating the content
+        // ahead of time (see calculateIntegrations), the same generation
+        // `--apply` itself would run.
+        summary.unchanged++;
       } else {
-        // Check if block hash differs from what we'd generate
-        // We always update integrations since content is generated dynamically
+        // Either the hashes genuinely differ, or one side has no hash to
+        // compare (generation failed, or an older/mocked desired state that
+        // never computed one) — in which case this falls back to the
+        // previous unconditional behavior rather than silently doing nothing.
         actions.push({
           type: 'migrate_block',
           category: 'integration',
           path: desiredEntry.relativePath,
-          reason: 'integration content may need update',
+          reason: (desiredEntry.hash && actualEntry.hash)
+            ? 'integration content differs from what would be generated'
+            : 'integration content may need update (no hash available for comparison)',
           details: {
             toolName: desiredEntry.metadata.toolName,
             format: desiredEntry.metadata.format,
             currentBlockHash: actualEntry.metadata?.blockHash?.blockHash,
+            desiredBlockHash: desiredEntry.hash,
             metadata: desiredEntry.metadata
           }
         });

package/src/reconciler/plan-executor.js

@@ -22,7 +22,7 @@ import {
 import { writeManifest } from '../core/manifest.js';
 import { getRepositoryInfo } from '../utils/registry.js';
 import { displayLanguageToLocale } from '../utils/locale.js';
-import { computeFileHash } from '../utils/hasher.js';
+import { computeFileHash, pruneIntegrationFileHashes } from '../utils/hasher.js';
 import { createBackup, cleanupBackups } from './backup-manager.js';
 
 /**
@@ -179,6 +179,11 @@ export async function executePlan(projectPath, plan, manifest, options = {}) {
   // Write updated manifest
   if (!dryRun) {
     try {
+      // XSPEC-418 R6: catches any stale whole-file entry for an integration
+      // file this particular plan didn't touch (e.g. `--plan --skills` never
+      // reaches executeMigrateBlock), not just the one this run might
+      // otherwise have added.
+      pruneIntegrationFileHashes(updatedManifest);
       writeManifest(updatedManifest, projectPath);
     } catch (err) {
       results.push({
@@ -351,21 +356,17 @@ function executeMigrateBlock(projectPath, action, manifest) {
     if (result.blockHashInfo) {
       manifest.integrationBlockHashes[result.path] = result.blockHashInfo;
     }
-    // `init` also records integration files in the whole-file `fileHashes`, which
-    // is what `uds check`'s File Integrity compares. Rewriting the block without
-    // refreshing that entry left the file permanently reported as "modified" —
-    // a successful reconcile that reads, afterwards, as a damaged install.
-    // (XSPEC-343 R2)
-    const tracked = manifest.fileHashes?.[result.path];
-    if (tracked) {
-      const info = computeFileHash(join(projectPath, result.path));
-      if (info) {
-        manifest.fileHashes[result.path] = {
-          ...info,
-          installedAt: tracked.installedAt || new Date().toISOString()
-        };
-      }
-    }
+    // XSPEC-418 R6 supersedes the XSPEC-343 R2 fix this replaces. That fix
+    // refreshed a whole-file `fileHashes` entry here if one already existed,
+    // reasoning that leaving it stale would report the file "modified"
+    // forever. Refreshing it does stop that — but a whole-file hash for an
+    // integration file disagrees with reality the moment the adopter edits
+    // anything OUTSIDE the block, which the marker-based update above
+    // deliberately leaves alone; "modified" then fires for content UDS itself
+    // says it preserves, and contradicts the same run's block-integrity
+    // check. The correct fix is for this path not to be in `fileHashes` at
+    // all — it is tracked by the block hash above instead.
+    if (manifest.fileHashes) delete manifest.fileHashes[result.path];
     return { action, success: true };
   }
 

package/src/utils/hasher.js

@@ -4,6 +4,7 @@ import { join, relative } from 'path';
 import { UDS_MARKERS } from '../core/constants.js';
 import { resolveIntegrationFile } from '../core/constants.js';
 import { isProvenanceEstablished } from '../core/manifest.js';
+import { locateMarkerBlock, AmbiguousMarkerError } from './marker-locator.js';
 
 // GitHub issue #155. `git config core.autocrlf true` (the common
 // Windows default) rewrites LF to CRLF on checkout. The manifest's stored
@@ -472,13 +473,16 @@ function detectFormat(filePath) {
  */
 function extractBlockContent(content, format) {
   const markers = UDS_MARKERS[format] || UDS_MARKERS.markdown;
-  const startIdx = content.indexOf(markers.start);
-  const endIdx = content.indexOf(markers.end);
+  // XSPEC adopter-report Q5: locateMarkerBlock only counts a marker when it
+  // occupies a whole line by itself, not merely appears somewhere on one —
+  // see marker-locator.js for why raw indexOf broke on real files.
+  const block = locateMarkerBlock(content, markers);
 
-  if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+  if (!block) {
     return { before: content, blockContent: '', after: '' };
   }
 
+  const { startIdx, endIdx } = block;
   return {
     before: content.substring(0, startIdx),
     blockContent: content.substring(startIdx + markers.start.length, endIdx).trim(),
@@ -515,7 +519,15 @@ export function computeIntegrationBlockHash(filePath) {
       fullHash: `sha256:${fullHash}`,
       fullSize: Buffer.byteLength(content, 'utf-8')
     };
-  } catch {
+  } catch (error) {
+    // XSPEC adopter-report Q5: an ambiguous marker pair (two real START or
+    // END lines) is a distinct, reportable condition — not "no markers
+    // found". Every other error (unreadable file, etc.) keeps the original
+    // silent-null behavior; callers that need to surface the ambiguity to a
+    // user must catch AmbiguousMarkerError explicitly (see check.js).
+    if (error instanceof AmbiguousMarkerError) {
+      throw error;
+    }
     return null;
   }
 }
@@ -631,7 +643,14 @@ export function compareDirectoryHashes(dirPath, storedHashes, baseKey = '') {
 
 /**
  * Refresh all integrationBlockHashes in manifest by recalculating from disk
- * Ensures manifest hashes always match actual file content
+ * Ensures manifest hashes always match actual file content.
+ *
+ * Also prunes any `fileHashes` entry for the same paths (XSPEC-418 R6) — every
+ * call site of this function is a "we just wrote/restored an integration file,
+ * about to persist the manifest" checkpoint, which is exactly where a stale
+ * whole-file hash for that same path (written by an older CLI, or a write path
+ * this fix missed) needs to stop existing. See `pruneIntegrationFileHashes`.
+ *
  * @param {Object} manifest - Manifest object (mutated in place)
  * @param {string} projectPath - Project root path
  * @returns {Object} The updated manifest
@@ -652,5 +671,42 @@ export function refreshIntegrationBlockHashes(manifest, projectPath) {
     }
   }
 
+  pruneIntegrationFileHashes(manifest);
+
   return manifest;
 }
+
+/**
+ * Remove `fileHashes` entries for files UDS tracks by their UDS block instead
+ * (`integrationBlockHashes`) — CLAUDE.md, CLAUDE.local.md, AGENTS.md, GEMINI.md,
+ * etc. (XSPEC-418 R6).
+ *
+ * An integration file's whole-file hash and its block hash disagree the
+ * moment an adopter edits anything OUTSIDE the UDS block — exactly the
+ * customization UDS's marker-based update promises to preserve. Several write
+ * paths (`uds update`, `uds update --integrations-only`, `uds check
+ * --restore`, `uds check --migrate`) used to add a whole-file entry for these
+ * paths anyway, so `uds check --ci` could report "CLAUDE.md (modified)" from
+ * standards-file integrity in the same run its own block-integrity check said
+ * the block was intact — the two checks contradicted each other, and the one
+ * that failed was the one punishing content UDS says it preserves.
+ *
+ * `manifest.integrationBlockHashes` is the authoritative registry of which
+ * paths are integration files — every writer of it (`writeIntegrationFile`,
+ * `writeAgentsMdSummary`) sets an entry there and nowhere else, so keying off
+ * its keys needs no second list of "known" integration files to keep in sync.
+ *
+ * @param {Object} manifest - Manifest object (mutated in place)
+ * @returns {string[]} Paths whose stale whole-file hash was removed
+ */
+export function pruneIntegrationFileHashes(manifest) {
+  if (!manifest?.fileHashes || !manifest?.integrationBlockHashes) return [];
+  const removed = [];
+  for (const path of Object.keys(manifest.integrationBlockHashes)) {
+    if (path in manifest.fileHashes) {
+      delete manifest.fileHashes[path];
+      removed.push(path);
+    }
+  }
+  return removed;
+}