universal-dev-standards 5.16.0 → 6.0.0

package/src/i18n/messages.js

@@ -75,37 +75,6 @@ export const messages = {
       deleted: 'Spec deleted.'
     },
 
-    // Mission Command
-    mission: {
-      activeExists: 'An active mission already exists:',
-      existingAction: 'What would you like to do?',
-      resume: 'Resume existing mission',
-      cancel: 'Cancel existing and start new',
-      abort: 'Abort (do nothing)',
-      aborted: 'Operation cancelled.',
-      resuming: 'Resuming existing mission...',
-      previousCancelled: 'Previous mission cancelled.',
-      selectType: 'Select mission type:',
-      enterIntent: 'Describe your goal:',
-      intentRequired: 'Intent is required',
-      created: 'Mission created!',
-      suggestedWorkflow: 'Suggested workflow:',
-      nextSteps: 'Next steps:',
-      useSpecCreate: 'Create specs:',
-      useStatus: 'Check status:',
-      usePause: 'Pause mission:',
-      planningPhase: 'Mission is now in planning phase.',
-      noActive: 'No active mission.',
-      startHint: 'Start one with: uds start <type> "<intent>"',
-      paused: 'Mission paused.',
-      resumed: 'Mission resumed!',
-      confirmCancel: 'Cancel this mission?',
-      cancelAborted: 'Operation cancelled.',
-      cancelled: 'Mission cancelled.',
-      noMissions: 'No missions found.',
-      listTitle: 'Missions:'
-    },
-
     // Display Language (first prompt - English only since language not yet selected)
     displayLanguage: {
       title: 'Display Language',
@@ -673,8 +642,6 @@ export const messages = {
       vibeMode: 'Vibe Coding Mode - For AI-assisted development',
       missionMode: 'Mission Mode - For goal-oriented development',
       customMode: 'Custom - Set individual options',
-      missionComingSoon: 'Mission mode setup coming soon!',
-      useStartCommand: 'For now, use: uds start <mission-type> <intent>',
       customHint: 'Use: uds config set <key> <value>',
       vibeModeTitle: 'Vibe Coding Configuration',
       vibeModeDesc: 'Configure UDS for natural language-driven development',
@@ -700,7 +667,7 @@ export const messages = {
       nextSteps: 'Next steps:',
       useSpec: 'Generate specs:',
       useSweep: 'Clean up code:',
-      useStart: 'Start a mission:',
+      useQuickstart: 'Explore recipes:',
       // Display Language
       displayLanguageOption: 'Display Language - Change UI language',
       currentLanguage: 'Current language',
@@ -1340,37 +1307,6 @@ export const messages = {
       deleted: '規格已刪除。'
     },
 
-    // Mission Command
-    mission: {
-      activeExists: '已存在進行中的任務：',
-      existingAction: '您想怎麼做？',
-      resume: '繼續現有任務',
-      cancel: '取消現有任務並開始新任務',
-      abort: '中止（不執行任何操作）',
-      aborted: '操作已取消。',
-      resuming: '正在繼續現有任務...',
-      previousCancelled: '已取消先前任務。',
-      selectType: '選擇任務類型：',
-      enterIntent: '描述您的目標：',
-      intentRequired: '必須提供意圖描述',
-      created: '任務已建立！',
-      suggestedWorkflow: '建議的工作流程：',
-      nextSteps: '後續步驟：',
-      useSpecCreate: '建立規格：',
-      useStatus: '查看狀態：',
-      usePause: '暫停任務：',
-      planningPhase: '任務現在處於規劃階段。',
-      noActive: '沒有進行中的任務。',
-      startHint: '使用以下命令開始：uds start <類型> "<意圖>"',
-      paused: '任務已暫停。',
-      resumed: '任務已繼續！',
-      confirmCancel: '確定要取消此任務嗎？',
-      cancelAborted: '操作已取消。',
-      cancelled: '任務已取消。',
-      noMissions: '找不到任務。',
-      listTitle: '任務列表：'
-    },
-
     // Display Language (first prompt - English only since language not yet selected)
     displayLanguage: {
       title: 'Display Language',
@@ -1938,8 +1874,6 @@ export const messages = {
       vibeMode: 'Vibe Coding 模式 - AI 輔助開發',
       missionMode: 'Mission 模式 - 目標導向開發',
       customMode: '自訂 - 個別設定選項',
-      missionComingSoon: 'Mission 模式設定即將推出！',
-      useStartCommand: '目前請使用：uds start <mission-type> <intent>',
       customHint: '使用：uds config set <key> <value>',
       vibeModeTitle: 'Vibe Coding 設定',
       vibeModeDesc: '設定 UDS 以進行自然語言驅動開發',
@@ -1965,7 +1899,7 @@ export const messages = {
       nextSteps: '後續步驟：',
       useSpec: '產生規格：',
       useSweep: '清理程式碼：',
-      useStart: '開始任務：',
+      useQuickstart: '探索工作流程範例：',
       // Display Language
       displayLanguageOption: '顯示語言 - 變更 UI 語言',
       currentLanguage: '目前語言',
@@ -2604,37 +2538,6 @@ export const messages = {
       deleted: '规格已删除。'
     },
 
-    // Mission Command
-    mission: {
-      activeExists: '已存在进行中的任务：',
-      existingAction: '您想怎么做？',
-      resume: '继续现有任务',
-      cancel: '取消现有任务并开始新任务',
-      abort: '中止（不执行任何操作）',
-      aborted: '操作已取消。',
-      resuming: '正在继续现有任务...',
-      previousCancelled: '已取消先前任务。',
-      selectType: '选择任务类型：',
-      enterIntent: '描述您的目标：',
-      intentRequired: '必须提供意图描述',
-      created: '任务已创建！',
-      suggestedWorkflow: '建议的工作流程：',
-      nextSteps: '后续步骤：',
-      useSpecCreate: '创建规格：',
-      useStatus: '查看状态：',
-      usePause: '暂停任务：',
-      planningPhase: '任务现在处于规划阶段。',
-      noActive: '没有进行中的任务。',
-      startHint: '使用以下命令开始：uds start <类型> "<意图>"',
-      paused: '任务已暂停。',
-      resumed: '任务已继续！',
-      confirmCancel: '确定要取消此任务吗？',
-      cancelAborted: '操作已取消。',
-      cancelled: '任务已取消。',
-      noMissions: '找不到任务。',
-      listTitle: '任务列表：'
-    },
-
     // Display Language (first prompt - English only since language not yet selected)
     displayLanguage: {
       title: 'Display Language',
@@ -3131,8 +3034,6 @@ export const messages = {
       vibeMode: 'Vibe Coding 模式 - AI 辅助开发',
       missionMode: 'Mission 模式 - 目标导向开发',
       customMode: '自定义 - 单独设置选项',
-      missionComingSoon: 'Mission 模式设置即将推出！',
-      useStartCommand: '目前请使用：uds start <mission-type> <intent>',
       customHint: '使用：uds config set <key> <value>',
       vibeModeTitle: 'Vibe Coding 配置',
       vibeModeDesc: '配置 UDS 以进行自然语言驱动开发',
@@ -3158,7 +3059,7 @@ export const messages = {
       nextSteps: '后续步骤：',
       useSpec: '生成规格：',
       useSweep: '清理代码：',
-      useStart: '开始任务：',
+      useQuickstart: '探索工作流程示例：',
       // Display Language
       displayLanguageOption: '显示语言 - 更改 UI 语言',
       currentLanguage: '当前语言',

package/src/missions/MissionManager.js

@@ -26,22 +26,29 @@ export const MissionState = {
   REVIEW: 'review',
   COMPLETED: 'completed',
   PAUSED: 'paused',
-  CANCELLED: 'cancelled'
+  CANCELLED: 'cancelled',
+  // Terminal failure state (T11 / XSPEC-292 §9.2): a mission that cannot
+  // proceed (unrecoverable error / abandoned). Like COMPLETED and CANCELLED it
+  // is terminal and cannot be resumed.
+  FAILED: 'failed'
 };
 
 /**
- * Valid state transitions
+ * Valid state transitions.
+ * Any active (non-terminal) state may transition to FAILED; terminal states
+ * (COMPLETED / CANCELLED / FAILED) have no outgoing transitions.
  */
 const STATE_TRANSITIONS = {
-  [MissionState.CREATED]: [MissionState.PLANNING, MissionState.CANCELLED],
-  [MissionState.PLANNING]: [MissionState.SPEC_PENDING, MissionState.PAUSED, MissionState.CANCELLED],
-  [MissionState.SPEC_PENDING]: [MissionState.SPEC_CONFIRMED, MissionState.PLANNING, MissionState.CANCELLED],
-  [MissionState.SPEC_CONFIRMED]: [MissionState.IN_PROGRESS, MissionState.PAUSED, MissionState.CANCELLED],
-  [MissionState.IN_PROGRESS]: [MissionState.REVIEW, MissionState.PAUSED, MissionState.CANCELLED],
-  [MissionState.REVIEW]: [MissionState.COMPLETED, MissionState.IN_PROGRESS, MissionState.CANCELLED],
-  [MissionState.PAUSED]: [MissionState.PLANNING, MissionState.IN_PROGRESS, MissionState.CANCELLED],
+  [MissionState.CREATED]: [MissionState.PLANNING, MissionState.CANCELLED, MissionState.FAILED],
+  [MissionState.PLANNING]: [MissionState.SPEC_PENDING, MissionState.PAUSED, MissionState.CANCELLED, MissionState.FAILED],
+  [MissionState.SPEC_PENDING]: [MissionState.SPEC_CONFIRMED, MissionState.PLANNING, MissionState.CANCELLED, MissionState.FAILED],
+  [MissionState.SPEC_CONFIRMED]: [MissionState.IN_PROGRESS, MissionState.PAUSED, MissionState.CANCELLED, MissionState.FAILED],
+  [MissionState.IN_PROGRESS]: [MissionState.REVIEW, MissionState.PAUSED, MissionState.CANCELLED, MissionState.FAILED],
+  [MissionState.REVIEW]: [MissionState.COMPLETED, MissionState.IN_PROGRESS, MissionState.CANCELLED, MissionState.FAILED],
+  [MissionState.PAUSED]: [MissionState.PLANNING, MissionState.IN_PROGRESS, MissionState.CANCELLED, MissionState.FAILED],
   [MissionState.COMPLETED]: [],
-  [MissionState.CANCELLED]: []
+  [MissionState.CANCELLED]: [],
+  [MissionState.FAILED]: []
 };
 
 /**
@@ -157,12 +164,14 @@ export class MissionManager {
   }
 
   /**
-   * Check if state is terminal (completed or cancelled)
+   * Check if state is terminal (completed, cancelled, or failed)
    * @param {string} state - Mission state
    * @returns {boolean}
    */
   isTerminalState(state) {
-    return state === MissionState.COMPLETED || state === MissionState.CANCELLED;
+    return state === MissionState.COMPLETED
+      || state === MissionState.CANCELLED
+      || state === MissionState.FAILED;
   }
 
   /**
@@ -188,6 +197,15 @@ export class MissionManager {
       throw new Error('No active mission found');
     }
 
+    // Resume guard (T11 / XSPEC-292 §9.2): terminal states are final. A
+    // completed / cancelled / failed mission must never be revived — fail
+    // loudly instead of silently re-activating an archived mission.
+    if (this.isTerminalState(mission.state)) {
+      throw new Error(
+        `Mission ${mission.id} is in terminal state '${mission.state}' and cannot be transitioned or resumed.`
+      );
+    }
+
     if (!this.canTransition(mission.state, toState)) {
       throw new Error(
         `Invalid transition: ${mission.state} → ${toState}. ` +
@@ -431,6 +449,20 @@ export class MissionManager {
     return this.transition(MissionState.CANCELLED, { reason });
   }
 
+  /**
+   * Mark current mission as FAILED (terminal).
+   *
+   * Used when a mission cannot proceed — an unrecoverable error or an abandoned
+   * run. Unlike {@link pause}, a failed mission is archived to history and can
+   * never be resumed (see the resume guard in {@link transition}).
+   *
+   * @param {string} reason - Reason for the failure
+   * @returns {Object} Failed mission
+   */
+  fail(reason = '') {
+    return this.transition(MissionState.FAILED, { reason });
+  }
+
   /**
    * Complete current mission
    * @param {Object} summary - Completion summary

package/src/utils/build-manifest.js

@@ -26,12 +26,28 @@ export function createManifest({ version, commit, builder, checksum, branch }) {
   };
 }
 
+/** Normalize a checksum for comparison: drop an optional `sha256:` prefix, lowercase, trim. */
+function normalizeChecksum(value) {
+  return String(value).trim().replace(/^sha256:/i, '').toLowerCase();
+}
+
 /**
- * Verify a manifest against a Git tag's commit hash.
- * Returns { valid: boolean, errors: string[] }.
+ * Verify a manifest against a Git tag's commit hash, and — when the manifest
+ * records a package checksum — against the artefact's actual checksum.
+ *
+ * T13 (XSPEC-292): the manifest carries `checksum.package`, but earlier this
+ * function only compared the commit. Recording a checksum that nothing verifies
+ * is a false integrity guarantee, so verify now consumes it.
+ *
+ * @param {object} manifest
+ * @param {string} gitTagCommit
+ * @param {{ actualChecksum?: string }} [options] - actualChecksum: SHA256 of the
+ *        packaged artefact (computed by the caller). Omit when no artefact is at hand.
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
  */
-export function verifyManifest(manifest, gitTagCommit) {
+export function verifyManifest(manifest, gitTagCommit, options = {}) {
   const errors = [];
+  const warnings = [];
 
   if (!manifest.commit) {
     errors.push('manifest missing commit field');
@@ -39,8 +55,24 @@ export function verifyManifest(manifest, gitTagCommit) {
     errors.push(`commit mismatch: manifest has "${manifest.commit}", git tag points to "${gitTagCommit}"`);
   }
 
+  const recorded = manifest.checksum?.package ?? null;
+  if (recorded) {
+    const { actualChecksum } = options;
+    if (actualChecksum == null) {
+      warnings.push(
+        'checksum recorded in manifest but no artefact provided to verify against ' +
+        '(pass --artifact <path> to verify integrity)'
+      );
+    } else if (normalizeChecksum(actualChecksum) !== normalizeChecksum(recorded)) {
+      errors.push(
+        `checksum mismatch: manifest records "${recorded}", artefact computes to "${actualChecksum}"`
+      );
+    }
+  }
+
   return {
     valid: errors.length === 0,
     errors,
+    warnings,
   };
 }

package/src/utils/friction-detector.js

@@ -114,26 +114,51 @@ function detectUnusedStandards(projectPath, manifest) {
 
   const allConfigText = configContents.join('\n');
 
-  // Check each standard file (handles both ID format and legacy path format)
+  // Build a filename -> canonical id index from the registry. AI configs
+  // reference a standard by its canonical id (e.g. `.standards/ai-agreement`),
+  // which often diverges from the installed filename: most files carry a
+  // `-standards` suffix the id drops, and a few diverge entirely
+  // (error-codes.ai.yaml -> id error-code-standards). Matching only on the
+  // filename therefore produced false "unused" findings whose remediation is
+  // `uds uninstall` — i.e. it could remove standards that are in active use. (#125)
   const allStdsFriction = getAllStandards();
   const frictionFormat = manifest.format || 'ai';
-  const standardFiles = (manifest.standards || []).map(s => {
+  const fileNameToId = new Map();
+  for (const entry of allStdsFriction) {
+    const src = getStandardSource(entry, frictionFormat) || getStandardSource(entry, 'human');
+    if (src) fileNameToId.set(src.split('/').pop(), entry.id);
+  }
+
+  // Resolve each manifest standard to its canonical id + filename
+  // (handles both ID format and legacy path format)
+  const standardRefs = (manifest.standards || []).map(s => {
+    let id;
+    let fileName;
     if (!s.includes('/') && !s.includes('.')) {
-      // ID format: resolve to actual filename
+      // ID format: the entry itself is the id; resolve filename via registry
+      id = s;
       const entry = allStdsFriction.find(r => r.id === s);
-      if (entry) {
-        const src = getStandardSource(entry, frictionFormat);
-        if (src) return src.split('/').pop();
-      }
-      return s;
+      const src = entry ? getStandardSource(entry, frictionFormat) : null;
+      fileName = src ? src.split('/').pop() : s;
+    } else {
+      // Path format: derive filename, then look up canonical id
+      fileName = s.split('/').pop();
+      id = fileNameToId.get(fileName) || null;
     }
-    return s.split('/').pop();
+    return { id, fileName };
   });
 
-  for (const fileName of standardFiles) {
-    // Check if the filename (without extension) is referenced
+  for (const { id, fileName } of standardRefs) {
     const baseName = fileName.replace(/\.ai\.yaml$/, '').replace(/\.md$/, '');
-    if (!allConfigText.includes(fileName) && !allConfigText.includes(baseName)) {
+    // Candidate reference tokens, canonical id first. The trailing
+    // `-standards` strip is a defensive fallback for standards absent from the
+    // registry. A match on any token means the standard is referenced — erring
+    // toward "referenced" is the safe direction (avoid uninstall-driven data loss).
+    const candidates = [id, fileName, baseName, baseName.replace(/-standards$/, '')]
+      .filter(Boolean);
+    const referenced = candidates.some(token => allConfigText.includes(token));
+
+    if (!referenced) {
       frictions.push({
         standard: fileName,
         type: 'unused',
@@ -162,25 +187,24 @@ function detectOrphanedFiles(projectPath, manifest) {
   // Get list of tracked files from manifest
   const trackedFiles = new Set();
 
-  // From fileHashes
+  // From fileHashes (normalize separators so Windows-written manifests match)
   if (manifest.fileHashes) {
     for (const key of Object.keys(manifest.fileHashes)) {
       if (key.startsWith('.standards/') || key.startsWith('.standards\\')) {
-        trackedFiles.add(key.replace(/^\.standards[/\\]/, ''));
+        trackedFiles.add(key.replace(/^\.standards[/\\]/, '').replaceAll('\\', '/'));
       }
     }
   }
 
-  // Always exclude manifest.json
+  // Always exclude UDS-managed files that are not hash-tracked
   trackedFiles.add('manifest.json');
+  trackedFiles.add('release-config.yaml'); // written by `uds config` (#115)
 
-  // Scan .standards/ directory
-  let actualFiles;
-  try {
-    actualFiles = readdirSync(standardsDir).filter(f => f !== 'manifest.json');
-  } catch {
-    return frictions;
-  }
+  // Scan .standards/ recursively — option standards live in subdirectories
+  // such as .standards/options/, which a flat readdir reports as an
+  // orphaned "options" entry (#115)
+  const actualFiles = collectRelativeFilePaths(standardsDir)
+    .filter(f => f !== 'manifest.json');
 
   for (const fileName of actualFiles) {
     if (!trackedFiles.has(fileName)) {
@@ -196,3 +220,28 @@ function detectOrphanedFiles(projectPath, manifest) {
 
   return frictions;
 }
+
+/**
+ * Recursively list files under a directory as '/'-separated relative paths
+ * @param {string} baseDir
+ * @param {string} prefix
+ * @param {Array<string>} acc
+ * @returns {Array<string>}
+ */
+function collectRelativeFilePaths(baseDir, prefix = '', acc = []) {
+  let entries;
+  try {
+    entries = readdirSync(baseDir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      collectRelativeFilePaths(join(baseDir, entry.name), relPath, acc);
+    } else {
+      acc.push(relPath);
+    }
+  }
+  return acc;
+}

package/src/utils/health-checker.js

@@ -11,7 +11,7 @@
  * @see docs/specs/system/SPEC-AUDIT-01-standards-audit.md (AC-1)
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { readManifest } from './copier.js';
 import { compareFileHash, hasFileHashes } from './hasher.js';
@@ -67,6 +67,9 @@ export function runHealthCheck(projectPath) {
   if (manifest.standards && Array.isArray(manifest.standards)) {
     const allStds = getAllStandards();
     const stdFormat = manifest.format || 'ai';
+    // Option standards install under subdirectories (e.g. .standards/options/),
+    // so a root-only existence check reports them as false "missing" (#115)
+    const installedFileNames = collectInstalledFileNames(standardsDir);
     for (const standardId of manifest.standards) {
       // Resolve ID-format to actual filename via registry
       let fileName;
@@ -82,7 +85,7 @@ export function runHealthCheck(projectPath) {
         fileName = standardId.split('/').pop();
       }
       const filePath = join(standardsDir, fileName);
-      if (!existsSync(filePath)) {
+      if (!existsSync(filePath) && !installedFileNames.has(fileName)) {
         issues.push({
           severity: 'WARNING',
           component: fileName,
@@ -111,6 +114,30 @@ export function runHealthCheck(projectPath) {
   return { status, issues };
 }
 
+/**
+ * Recursively collect file basenames installed under .standards/
+ * (option standards live in subdirectories such as .standards/options/ — #115)
+ * @param {string} dir
+ * @param {Set<string>} names
+ * @returns {Set<string>}
+ */
+function collectInstalledFileNames(dir, names = new Set()) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return names;
+  }
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      collectInstalledFileNames(join(dir, entry.name), names);
+    } else {
+      names.add(entry.name);
+    }
+  }
+  return names;
+}
+
 /**
  * Check file hashes against manifest
  * @param {string} projectPath

package/src/utils/transaction.js

@@ -0,0 +1,111 @@
+/**
+ * File transaction wrapper — backup → apply → verify → rollback.
+ *
+ * Makes a multi-step, file-mutating operation atomic from the caller's point of
+ * view: snapshot the files/dirs the operation may touch, run `apply()`, then
+ * `verify()` the result. If `apply()` throws or `verify()` returns false, every
+ * tracked path is restored to its pre-apply state and the error is re-thrown
+ * (annotated with `rolledBack`). On success the changes are committed (left in
+ * place) and the apply() result is returned.
+ *
+ * Rollback semantics per tracked path:
+ *   - pre-existing FILE  → original content rewritten
+ *   - pre-existing DIR   → left intact (its prior contents are unknown, so we
+ *                          never tear it down; do not track shared dirs you do
+ *                          not fully own)
+ *   - path created by apply() (file or dir) → removed (dirs recursively)
+ *
+ * XSPEC-292 §9.2 (T11): CLI transactionality. Used by `init`, `spec-split`, and
+ * other commands that perform several dependent writes.
+ *
+ * @module utils/transaction
+ */
+
+import {
+  existsSync, statSync, readFileSync, writeFileSync, mkdirSync, rmSync
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * @typedef {Object} TransactionHooks
+ * @property {() => (any|Promise<any>)} apply  Performs the file mutations.
+ * @property {(result:any) => (boolean|Promise<boolean>)} [verify]
+ *   Returns false (or throws) to trigger rollback. Omit to always commit.
+ */
+
+/**
+ * Run `apply` as a transaction over `paths`.
+ *
+ * @param {string[]} paths - Absolute paths the operation may create/modify/delete.
+ * @param {TransactionHooks} hooks
+ * @param {Object} [options]
+ * @param {string} [options.label] - Included in the verification error message.
+ * @returns {Promise<{result:any, rolledBack:false}>}
+ * @throws Re-throws the original error after rolling back. The thrown error has
+ *   `rolledBack` set to `true` (rollback succeeded) or `false` (rollback also
+ *   failed, with `rollbackError` attached).
+ */
+export async function withFileTransaction(paths, hooks = {}, options = {}) {
+  const { apply, verify } = hooks;
+  if (typeof apply !== 'function') {
+    throw new TypeError('withFileTransaction requires an apply() function');
+  }
+
+  // 1. Backup: snapshot current state of every tracked path.
+  const snapshot = (paths || []).map((path) => {
+    const existed = existsSync(path);
+    const isDir = existed && statSync(path).isDirectory();
+    return {
+      path,
+      existed,
+      isDir,
+      content: existed && !isDir ? readFileSync(path) : null
+    };
+  });
+
+  const rollback = () => {
+    // Restore deepest paths first so children settle before parents.
+    for (const entry of [...snapshot].reverse()) {
+      if (entry.existed) {
+        if (!entry.isDir) {
+          mkdirSync(dirname(entry.path), { recursive: true });
+          writeFileSync(entry.path, entry.content);
+        }
+        // Pre-existing directories are intentionally left untouched.
+      } else if (existsSync(entry.path)) {
+        // Created during apply() → remove it (recursively for directories).
+        rmSync(entry.path, { recursive: true, force: true });
+      }
+    }
+  };
+
+  let result;
+  try {
+    // 2. Apply.
+    result = await apply();
+
+    // 3. Verify.
+    if (typeof verify === 'function') {
+      const ok = await verify(result);
+      if (ok === false) {
+        const err = new Error(
+          `Transaction verification failed${options.label ? ` for ${options.label}` : ''}`
+        );
+        err.code = 'TRANSACTION_VERIFY_FAILED';
+        throw err;
+      }
+    }
+  } catch (err) {
+    // 4. Rollback.
+    try {
+      rollback();
+      err.rolledBack = true;
+    } catch (rollbackErr) {
+      err.rolledBack = false;
+      err.rollbackError = rollbackErr;
+    }
+    throw err;
+  }
+
+  return { result, rolledBack: false };
+}

package/src/utils/version-promote.js

@@ -6,6 +6,22 @@
 
 const RC_VERSION_REGEX = /^v?(\d+)\.(\d+)\.(\d+)-rc\.(\d+)$/;
 const SEMVER_REGEX = /^v?(\d+)\.(\d+)\.(\d+)(-[a-zA-Z]+\.\d+)?$/;
+const STABLE_VERSION_REGEX = /^v?(\d+)\.(\d+)\.(\d+)$/;
+
+/**
+ * True if `version` is a valid stable semver (X.Y.Z, optional leading v),
+ * with no pre-release suffix. Used to validate `uds release promote` targets.
+ */
+export function isStableVersion(version) {
+  return typeof version === 'string' && STABLE_VERSION_REGEX.test(version);
+}
+
+/**
+ * True if `version` is any valid semver this tool recognises (stable or RC).
+ */
+export function isValidVersion(version) {
+  return typeof version === 'string' && (SEMVER_REGEX.test(version) || RC_VERSION_REGEX.test(version));
+}
 
 /**
  * Parse an RC version string into its components.