universal-dev-standards 6.9.0 → 6.11.0

package/src/reconciler/diff-engine.js

@@ -14,6 +14,8 @@
  * Integration files use migrate_block: only the UDS marker block is replaced.
  */
 
+import { isShippedFilename } from '../utils/registry.js';
+
 /**
  * @typedef {Object} PlanAction
  * @property {'create'|'update'|'delete'|'migrate_block'|'patch_hook'} type
@@ -205,12 +207,18 @@ function diffCategory(desiredMap, actualMap, category, actions, warnings, summar
   // Check actual entries not in desired → delete (only if UDS-managed)
   for (const [key, actualEntry] of actualMap) {
     if (!desiredMap.has(key)) {
-      if (isUDSManaged(actualEntry)) {
+      if (isUserConfigPath(actualEntry.relativePath)) {
+        // Said out loud rather than skipped quietly: a plan that silently omits
+        // things is how the previous round of deletion bugs stayed invisible.
+        warnings.push(
+          `Keeping ${actualEntry.relativePath}: it holds a setting you chose (uds config writes it), not content UDS ships`
+        );
+      } else if (isUDSManaged(actualEntry)) {
         actions.push({
           type: 'delete',
           category,
           path: actualEntry.relativePath,
-          reason: 'no longer in desired state',
+          reason: describeDeletion(actualEntry.relativePath, category),
           details: {
             currentHash: actualEntry.hash,
             metadata: actualEntry.metadata
@@ -264,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
           }
         });
@@ -330,6 +354,53 @@ function diffIntegrations(desiredMap, actualMap, actions, warnings, summary, for
  * Files in .standards/ are always UDS-managed.
  * Skill/command entries from manifest installations are UDS-managed.
  */
+/**
+ * Files under `.standards/` that hold a choice the user made, not content UDS
+ * ships.
+ *
+ * `release-config.yaml` is written by `uds init` from the release mode the user
+ * picked and rewritten by `uds config`. Nothing in the desired-state calculator
+ * models it, so it fell out of every diff as "no longer in desired state" and
+ * into the delete plan — a plan that discards a user setting and calls that
+ * reconciliation. Reported 2026-09-16 by an adopter who could not tell from the
+ * plan whether the file held anything of theirs. It did.
+ *
+ * @param {string} relativePath
+ * @returns {boolean}
+ */
+export function isUserConfigPath(relativePath) {
+  const normalized = String(relativePath || '').replace(/\\/g, '/');
+  return normalized === '.standards/release-config.yaml';
+}
+
+/**
+ * Why this file is being deleted, in terms the adopter can act on.
+ *
+ * "no longer in desired state" was the reason given for a standard UDS retired
+ * upstream, an option the project deselected, and a path the desired state does
+ * not model — three different situations, three different right responses, one
+ * sentence. The distinction that matters most is the first one: if UDS still
+ * ships the file, the change came from this project and is reversible by
+ * re-selecting it; if UDS does not, it is gone upstream and re-selecting it will
+ * not bring it back.
+ *
+ * @param {string} relativePath
+ * @param {string} category - 'standard' | 'option' | 'skill' | 'command' | …
+ * @returns {string}
+ */
+export function describeDeletion(relativePath, category) {
+  const normalized = String(relativePath || '').replace(/\\/g, '/');
+
+  if (category === 'standard' || category === 'option') {
+    const fileName = normalized.split('/').pop();
+    return isShippedFilename(fileName)
+      ? 'this project no longer selects it (UDS still ships it, so re-selecting restores it)'
+      : 'UDS no longer ships this file (re-selecting will not bring it back)';
+  }
+
+  return `not part of what this project's manifest asks for (category: ${category})`;
+}
+
 function isUDSManaged(entry) {
   // Files in .standards/ are always UDS-managed
   if (entry.relativePath.startsWith('.standards/')) return true;

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 };
   }
 
@@ -436,6 +437,22 @@ async function executeSkillBatch(projectPath, skillActions, manifest) {
   return results;
 }
 
+/**
+ * Hash-map key for a command action: `<agent>/<file>`.
+ *
+ * `commandHashes` is keyed by agent and filename; a plan action carries a
+ * project-relative path (`.opencode/command/atdd.md`). Deleting by the wrong key
+ * leaves the entry behind and the next `check` reports the file missing.
+ */
+function commandHashKey(action) {
+  const meta = action.details?.metadata;
+  if (meta?.agent && meta?.commandName) return `${meta.agent}/${meta.commandName}.md`;
+  const parts = action.path.split('/').filter(Boolean);
+  const agent = parts[0] ? parts[0].replace(/^\./, '') : null;
+  const file = parts[parts.length - 1];
+  return agent && file ? `${agent}/${file}` : action.path;
+}
+
 /**
  * Batch execute command installations.
  */
@@ -452,6 +469,9 @@ async function executeCommandBatch(projectPath, commandActions, manifest) {
       if (existsSync(targetPath)) {
         rmSync(targetPath, { recursive: true, force: true });
       }
+      // A deleted file must also lose its hash entry, or the next check calls
+      // it missing for good.
+      delete manifest.commandHashes[commandHashKey(action)];
       results.push({ action, success: true });
     } catch (err) {
       results.push({ action, success: false, error: err.message });
@@ -475,17 +495,18 @@ async function executeCommandBatch(projectPath, commandActions, manifest) {
         );
 
         if (installResult.allFileHashes) {
-          // Clean up stale entries for agents being updated before merging
-          const updatedPrefixes = new Set(
-            Object.keys(installResult.allFileHashes).map(k => k.split('/')[0])
-          );
-          for (const prefix of updatedPrefixes) {
-            for (const key of Object.keys(manifest.commandHashes)) {
-              if (key.startsWith(prefix + '/')) {
-                delete manifest.commandHashes[key];
-              }
-            }
-          }
+          // Merge, exactly as the skill path above does.
+          //
+          // 🔴 This used to delete every key whose prefix matched an agent in the
+          // result before merging. That is correct only when the installer
+          // reinstalled ALL of that agent's commands — which `uds update`'s own
+          // call sites do (they pass `commandNames = null`). Here the plan names a
+          // subset, so the wipe threw away the entry for every command the plan did
+          // not mention. Measured on 6.9.0 (2026-09-16): a three-file drift turned
+          // 51 tracked commands into 3, the other 48 stayed on disk untracked, and
+          // `uds check` printed "All command files intact (3 files)" in the same run
+          // as "Commands: 51 installed" — tampering with one of the 48 changed
+          // neither line.
           Object.assign(manifest.commandHashes, installResult.allFileHashes);
         }
 

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;
+}