universal-dev-standards 5.17.0 → 6.1.0

package/src/commands/spec-split.js

@@ -12,6 +12,7 @@ import { checkbox, confirm as inquirerConfirm } from '@inquirer/prompts';
 import { MicroSpec } from '../vibe/micro-spec.js';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { withFileTransaction } from '../utils/transaction.js';
 
 /**
  * Extract acceptance criteria from spec markdown
@@ -135,7 +136,6 @@ export async function specSplitCommand(id, options = {}) {
   // Update original spec: add depends_on to new spec
   const originalContent = originalLines.join('\n');
   const updatedOriginal = addDependsOn(originalContent, newId);
-  writeFileSync(specPath, updatedOriginal, 'utf-8');
 
   // Create new spec with moved ACs
   const newSpec = {
@@ -154,7 +154,32 @@ export async function specSplitCommand(id, options = {}) {
     /\*\*Acceptance\*\*:[\s\S]*?(?=\n\*\*|$)/,
     `**Acceptance**:\n${acSection}`
   );
-  writeFileSync(newSpecPath, finalContent, 'utf-8');
+
+  // T11 (XSPEC-292 §9.2): the two writes must be atomic. If creating the new
+  // spec fails after the original was rewritten (ACs removed), the original
+  // would be corrupted and the moved ACs lost. Wrap both writes so any failure
+  // restores the original and removes a partially-written new spec.
+  try {
+    await withFileTransaction(
+      [specPath, newSpecPath],
+      {
+        apply: () => {
+          writeFileSync(specPath, updatedOriginal, 'utf-8');
+          writeFileSync(newSpecPath, finalContent, 'utf-8');
+        },
+        verify: () => existsSync(specPath) && existsSync(newSpecPath)
+      },
+      { label: `spec-split ${id}` }
+    );
+  } catch (err) {
+    console.log(chalk.red(`\nError: spec split failed and was rolled back: ${err.message}`));
+    console.log(chalk.gray(`  Original ${id} restored. Backup also at ${join(backupDir, `${id}-pre-split.md`)}`));
+    if (err.rolledBack === false) {
+      console.log(chalk.yellow(`  ⚠ Rollback also failed: ${err.rollbackError?.message}. Restore manually from the backup.`));
+    }
+    process.exit(1);
+    return;
+  }
 
   console.log(chalk.green('\nSplit complete:'));
   console.log(`  ${chalk.cyan(id)} — ${acs.length - toMove.length} ACs (updated)`);

package/src/commands/update.js

@@ -808,9 +808,18 @@ export async function updateCommand(options) {
   }
 
   // Update manifest
+  // T11 (XSPEC-292 §9.2): never record a partial failure as a completed update.
+  // If any standard/extension/integration copy failed, KEEP the previous
+  // upstream.version (and installed date) so that re-running `uds update`
+  // retries the failed files instead of treating the project as already up to
+  // date. The manifest is still written so that hash/migration bookkeeping for
+  // the files that DID succeed is persisted.
+  const updateIncomplete = results.errors.length > 0;
   manifest.version = '3.3.0';
-  manifest.upstream.version = latestVersion;
-  manifest.upstream.installed = new Date().toISOString().split('T')[0];
+  if (!updateIncomplete) {
+    manifest.upstream.version = latestVersion;
+    manifest.upstream.installed = new Date().toISOString().split('T')[0];
+  }
   refreshIntegrationBlockHashes(manifest, projectPath);
   writeManifest(manifest, projectPath);
 
@@ -893,8 +902,14 @@ export async function updateCommand(options) {
 
   // Summary
   console.log();
-  console.log(chalk.green(msg.updateSuccess));
-  console.log(chalk.gray(`  ${msg.versionUpdated.replace('{current}', currentVersion).replace('{latest}', latestVersion)}`));
+  if (updateIncomplete) {
+    // T11: surface the partial state honestly instead of claiming success.
+    console.log(chalk.yellow(msg.updateIncomplete ||
+      '⚠ Update incomplete — some files failed to update. Version NOT advanced; re-run `uds update` to retry.'));
+  } else {
+    console.log(chalk.green(msg.updateSuccess));
+    console.log(chalk.gray(`  ${msg.versionUpdated.replace('{current}', currentVersion).replace('{latest}', latestVersion)}`));
+  }
   if (results.integrations.length > 0) {
     console.log(chalk.gray(`  ${msg.integrationsSynced.replace('{count}', results.integrations.length)}`));
   }
@@ -1285,8 +1300,9 @@ export async function updateCommand(options) {
 
   console.log();
 
-  // Exit explicitly to prevent hanging
-  process.exit(0);
+  // Exit explicitly to prevent hanging.
+  // T11: a partial update exits non-zero so CI / scripts can detect the failure.
+  process.exit(updateIncomplete ? 1 : 0);
 }
 
 /**

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

@@ -471,7 +471,7 @@ export const AVAILABLE_COMMANDS = [
   // Core Development Workflow (Action Skills)
   // ═══════════════════════════════════════════════════════════════════════════
   { name: 'commit', description: 'Generate commit messages following Conventional Commits' },
-  { name: 'review', description: 'Perform code review with checklist' },
+  { name: 'code-review', description: 'Perform code review with checklist' },
   { name: 'checkin', description: 'Pre-commit quality gates verification' },
   { name: 'release', description: 'Guide release process' },
   { name: 'changelog', description: 'Generate changelog entries' },
@@ -484,6 +484,7 @@ export const AVAILABLE_COMMANDS = [
   { name: 'atdd', description: 'Guide ATDD workflow (acceptance criteria)' },
   { name: 'coverage', description: 'Analyze test coverage (8 dimensions)' },
   { name: 'ac-coverage', description: 'Generate AC traceability matrix and coverage report' },
+  { name: 'journey-test', description: 'Generate user journey test plan (TESTPLAN) and E2E skeletons' },
 
   // ═══════════════════════════════════════════════════════════════════════════
   // Specification and Requirements (Action Skills)
@@ -524,6 +525,7 @@ export const AVAILABLE_COMMANDS = [
   // ═══════════════════════════════════════════════════════════════════════════
   { name: 'methodology', description: 'Development methodology selection' },
   { name: 'dev-workflow', description: 'Guide for mapping development phases to UDS commands' },
+  { name: 'skill-builder', description: 'Identify repeated processes and build Skills with the right depth' },
 
   // ═══════════════════════════════════════════════════════════════════════════
   // Operations and Infrastructure (Action Skills)

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