universal-dev-standards 6.14.0-beta.5 → 6.14.0-beta.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +13 -3
  2. package/bin/uds.js +32 -7
  3. package/bundled/ai/options/code-review/pr-review.ai.yaml +20 -1
  4. package/bundled/ai/standards/code-review.ai.yaml +15 -2
  5. package/bundled/ai/standards/commit-message.ai.yaml +6 -2
  6. package/bundled/ai/standards/developer-memory.ai.yaml +12 -2
  7. package/bundled/ai/standards/full-coverage-testing.ai.yaml +44 -6
  8. package/bundled/ai/standards/open-work-tracking.ai.yaml +191 -11
  9. package/bundled/ai/standards/pipeline-security-gates.ai.yaml +48 -3
  10. package/bundled/ai/standards/project-context-memory.ai.yaml +12 -2
  11. package/bundled/core/code-review-checklist.md +20 -2
  12. package/bundled/core/developer-memory.md +12 -2
  13. package/bundled/core/full-coverage-testing.md +44 -4
  14. package/bundled/core/open-work-tracking.md +156 -16
  15. package/bundled/core/pipeline-security-gates.md +63 -0
  16. package/bundled/core/project-context-memory.md +10 -2
  17. package/bundled/locales/zh-CN/CHANGELOG.md +75 -3
  18. package/bundled/locales/zh-CN/README.md +1 -1
  19. package/bundled/locales/zh-CN/SECURITY.md +1 -1
  20. package/bundled/locales/zh-CN/adoption/ADOPTION-GUIDE.md +13 -4
  21. package/bundled/locales/zh-CN/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
  22. package/bundled/locales/zh-CN/adoption/checklists/enterprise.md +7 -1
  23. package/bundled/locales/zh-CN/adoption/checklists/minimal.md +13 -3
  24. package/bundled/locales/zh-CN/adoption/checklists/recommended.md +7 -1
  25. package/bundled/locales/zh-CN/core/code-review-checklist.md +17 -0
  26. package/bundled/locales/zh-CN/core/developer-memory.md +9 -0
  27. package/bundled/locales/zh-CN/core/full-coverage-testing.md +48 -8
  28. package/bundled/locales/zh-CN/core/pipeline-security-gates.md +64 -4
  29. package/bundled/locales/zh-CN/core/project-context-memory.md +5 -0
  30. package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +70 -0
  31. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +5 -4
  32. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +25 -23
  33. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +15 -12
  34. package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +6 -6
  35. package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md +7 -1
  36. package/bundled/locales/zh-CN/docs/user/GETTING-STARTED.md +44 -0
  37. package/bundled/locales/zh-CN/options/code-review/pr-review.md +13 -2
  38. package/bundled/locales/zh-TW/CHANGELOG.md +75 -3
  39. package/bundled/locales/zh-TW/README.md +1 -1
  40. package/bundled/locales/zh-TW/SECURITY.md +1 -1
  41. package/bundled/locales/zh-TW/adoption/ADOPTION-GUIDE.md +13 -4
  42. package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
  43. package/bundled/locales/zh-TW/adoption/checklists/enterprise.md +7 -1
  44. package/bundled/locales/zh-TW/adoption/checklists/minimal.md +13 -3
  45. package/bundled/locales/zh-TW/adoption/checklists/recommended.md +7 -1
  46. package/bundled/locales/zh-TW/core/code-review-checklist.md +17 -0
  47. package/bundled/locales/zh-TW/core/developer-memory.md +9 -0
  48. package/bundled/locales/zh-TW/core/full-coverage-testing.md +48 -8
  49. package/bundled/locales/zh-TW/core/open-work-tracking.md +90 -14
  50. package/bundled/locales/zh-TW/core/pipeline-security-gates.md +64 -4
  51. package/bundled/locales/zh-TW/core/project-context-memory.md +5 -0
  52. package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +70 -0
  53. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +5 -4
  54. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +25 -23
  55. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +15 -12
  56. package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +6 -6
  57. package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md +7 -1
  58. package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md +44 -0
  59. package/bundled/locales/zh-TW/options/code-review/pr-review.md +13 -2
  60. package/bundled/skills/SKILL_NAMING.md +9 -0
  61. package/bundled/templates/gates/check-anti-fake-tests.mjs +305 -5
  62. package/package.json +3 -1
  63. package/src/commands/audit.js +9 -2
  64. package/src/commands/check.js +17 -0
  65. package/src/commands/deps.js +31 -1
  66. package/src/commands/init.js +41 -21
  67. package/src/commands/open-work.js +65 -6
  68. package/src/commands/simulate.js +20 -8
  69. package/src/commands/skills.js +59 -33
  70. package/src/commands/spec.js +14 -8
  71. package/src/commands/update.js +106 -66
  72. package/src/core/manifest.js +12 -10
  73. package/src/core/marketplace-sentinel.js +5 -0
  74. package/src/core/open-work-config.js +103 -0
  75. package/src/core/project-config.js +58 -38
  76. package/src/flows/init-flow.js +10 -0
  77. package/src/i18n/messages.js +264 -60
  78. package/src/installers/skills-installer.js +3 -1
  79. package/src/prompts/init.js +148 -13
  80. package/src/reconciler/backup-locations.js +75 -0
  81. package/src/reconciler/backup-manager.js +29 -45
  82. package/src/reconciler/index.js +62 -8
  83. package/src/utils/available-standards-report.js +144 -0
  84. package/src/utils/available-standards.js +216 -0
  85. package/src/utils/commit-message-judge.js +137 -0
  86. package/src/utils/copier.js +5 -4
  87. package/src/utils/deps-applicability.js +25 -0
  88. package/src/utils/friction-detector.js +27 -0
  89. package/src/utils/installed-names-ownership.js +114 -0
  90. package/src/utils/open-work-tracking.mjs +919 -48
  91. package/src/utils/sdd-header.js +65 -0
  92. package/src/utils/skill-frontmatter.js +102 -0
  93. package/src/utils/skill-name-collision.js +169 -0
  94. package/src/utils/skills-install-paths.js +114 -0
  95. package/src/utils/skills-installer.js +63 -105
  96. package/src/utils/standard-validator.js +98 -27
  97. package/src/utils/transient-fs.js +113 -0
  98. package/src/vibe/micro-spec.js +15 -0
  99. package/standards-registry.json +9 -9
@@ -6,6 +6,12 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from '
6
6
  import { join, basename, dirname, relative } from 'path';
7
7
  import { readManifest, writeManifest, copyStandard, copyExtension, isInitialized, getRepoRoot } from '../utils/copier.js';
8
8
  import { getRepositoryInfo, getAllStandards, getShippableFilenames, getStandardSource } from '../utils/registry.js';
9
+ import { getAvailableStandards } from '../utils/available-standards.js';
10
+ import {
11
+ printAvailableStandardsSection,
12
+ resolveAddStandardRequest,
13
+ findAddStandardConflict
14
+ } from '../utils/available-standards-report.js';
9
15
  import { computeFileHash, planStandardsRemovals, refreshIntegrationBlockHashes, pruneIntegrationFileHashes } from '../utils/hasher.js';
10
16
  import { AmbiguousMarkerError } from '../utils/marker-locator.js';
11
17
  import {
@@ -27,6 +33,7 @@ import {
27
33
  import { checkForUpdates } from '../utils/npm-registry.js';
28
34
  import { pruneForeignSkillHashes } from '../utils/skill-hash-ownership.js';
29
35
  import { pruneForeignCommandHashes } from '../utils/command-hash-ownership.js';
36
+ import { pruneForeignSkillNames, pruneForeignCommandNames } from '../utils/installed-names-ownership.js';
30
37
  import { commandsUpdatedMessage } from '../utils/update-summary.js';
31
38
  import { t, setLanguage, isLanguageExplicitlySet } from '../i18n/messages.js';
32
39
  import { config } from '../utils/config-manager.js';
@@ -48,6 +55,7 @@ import {
48
55
  getCommandsDirForAgent
49
56
  } from '../config/ai-agent-paths.js';
50
57
  import { getMarketplaceSkillsInfo } from '../utils/github.js';
58
+ import { printSkillNameCollisionWarning } from '../utils/skill-name-collision.js';
51
59
  import { detectAITools } from '../utils/detector.js';
52
60
  import { HOOK_CAPABLE_TOOLS, resolveHookTools, installMissingHooks } from '../installers/hooks-installer.js';
53
61
  import { persistRecorder, mergeRecorderInto, newRecorder } from '../core/install-records.js';
@@ -322,43 +330,11 @@ async function updateCliAndExit(useBeta = false) {
322
330
  * @returns {{newStandards: Array<{source: string, name: string}>, count: number}}
323
331
  */
324
332
  function checkNewStandards(manifest) {
325
- const format = manifest.format || 'ai';
326
-
327
- // Get all standards (level system removed)
328
- const registryStandards = getAllStandards();
329
-
330
- // Include all reference and skill standards
331
- const eligibleStandards = registryStandards.filter(s => s.category === 'reference' || s.category === 'skill');
332
-
333
- // Get installed standard basenames for comparison.
334
- // Handles both legacy path format ("ai/standards/foo.ai.yaml" → basename "foo.ai.yaml")
335
- // and v3.4.0 ID format ("foo" → resolve to source path, then get basename).
336
- const installedBasenames = new Set();
337
- for (const s of (manifest.standards || [])) {
338
- if (s.includes('/options/') || s.startsWith('options/')) continue; // Skip option paths
339
- if (!s.includes('/') && !s.includes('.')) {
340
- // ID format: resolve to actual source filename via registry
341
- const entry = registryStandards.find(r => r.id === s);
342
- if (entry) {
343
- const sourcePath = getStandardSource(entry, format);
344
- if (sourcePath) installedBasenames.add(basename(sourcePath));
345
- }
346
- } else {
347
- installedBasenames.add(basename(s));
348
- }
349
- }
350
-
351
- // Find standards in registry that are not yet installed
352
- const newStandards = [];
353
- for (const std of eligibleStandards) {
354
- const sourcePath = getStandardSource(std, format);
355
- if (!sourcePath) continue; // Skip skill-only standards with no source file
356
- const fileName = basename(sourcePath);
357
- if (!installedBasenames.has(fileName)) {
358
- newStandards.push({ source: sourcePath, name: fileName });
359
- }
360
- }
361
-
333
+ // One definition of "available but not installed", shared with `update --plan`, `check` and
334
+ // `audit --friction` (XSPEC-458 R1). This function used to hold its own copy of that logic, and the
335
+ // reconciler path (`--plan`/`--apply`) held none — so the two paths disagreed about what was missing.
336
+ const { offered } = getAvailableStandards(manifest);
337
+ const newStandards = offered.map(std => ({ source: std.source, name: std.name }));
362
338
  return { newStandards, count: newStandards.length };
363
339
  }
364
340
 
@@ -453,6 +429,28 @@ export async function updateCommand(options) {
453
429
  console.log(chalk.bold(msg.title));
454
430
  console.log(chalk.gray('─'.repeat(50)));
455
431
 
432
+ // XSPEC-458 R3: `--add-standard <id>` (repeatable) picks standards UDS ships and this project lacks.
433
+ // Judged here, before any mode runs, so an unknown id stops everything instead of being skipped.
434
+ const addStandardIds = [].concat(options.addStandard || []);
435
+ let addStandards = [];
436
+ if (addStandardIds.length > 0) {
437
+ const conflict = findAddStandardConflict(options);
438
+ if (conflict) {
439
+ console.log(chalk.red(conflict));
440
+ console.log();
441
+ process.exitCode = 1;
442
+ return;
443
+ }
444
+ const request = resolveAddStandardRequest(manifest, addStandardIds);
445
+ if (!request.proceed) return;
446
+ if (request.ids.length === 0) {
447
+ console.log(chalk.gray(t().availableStandards.addNothingDone));
448
+ console.log();
449
+ return;
450
+ }
451
+ addStandards = request.ids;
452
+ }
453
+
456
454
  // Handle --claude-target option (XSPEC-418 R4): switch an EXISTING
457
455
  // installation's claude-code integration target between CLAUDE.md and
458
456
  // CLAUDE.local.md, without a full reinstall. Standalone, like --sync-refs
@@ -529,7 +527,7 @@ export async function updateCommand(options) {
529
527
  // Handle --plan option (DSR dry-run). Nothing below this line writes.
530
528
  if (options.plan) {
531
529
  if (!scopedToSkills && !scopedToCommands) {
532
- await handlePlan(projectPath, options, manifest);
530
+ await handlePlan(projectPath, options, manifest, addStandards);
533
531
  }
534
532
  if (scopedToSkills) await planSkills(projectPath, manifest, options);
535
533
  if (scopedToCommands) await planCommands(projectPath, manifest, options);
@@ -542,10 +540,10 @@ export async function updateCommand(options) {
542
540
  // files only when the manifest records them, so `--skills` is not redundant.
543
541
  if (options.apply || options.force) {
544
542
  if (!scopedToSkills && !scopedToCommands) {
545
- await handleReconcile(projectPath, options, { force: !!options.force });
543
+ await handleReconcile(projectPath, options, { force: !!options.force, addStandards });
546
544
  return;
547
545
  }
548
- await handleReconcile(projectPath, options, { force: !!options.force });
546
+ await handleReconcile(projectPath, options, { force: !!options.force, addStandards });
549
547
  // These exit the process on completion, so run Skills last.
550
548
  if (scopedToCommands) await updateCommandsOnly(projectPath, manifest, options);
551
549
  if (scopedToSkills) await updateSkillsOnly(projectPath, manifest, options);
@@ -631,6 +629,11 @@ export async function updateCommand(options) {
631
629
  // one who has nothing else to trigger the correction).
632
630
  const foreignSkillsOnLatest = pruneForeignSkillHashes(manifest);
633
631
  const foreignCommandsOnLatest = pruneForeignCommandHashes(manifest);
632
+ // XSPEC-456 R4: and the skill / command NAME lists (same reason).
633
+ const namesOnLatestBefore = (manifest.skills?.names?.length ?? 0) + (manifest.commands?.names?.length ?? 0);
634
+ pruneForeignSkillNames(manifest, projectPath);
635
+ pruneForeignCommandNames(manifest, projectPath);
636
+ const foreignNamesOnLatest = namesOnLatestBefore - (manifest.skills?.names?.length ?? 0) - (manifest.commands?.names?.length ?? 0);
634
637
  if (retiredOnLatest.length > 0) {
635
638
  console.log();
636
639
  console.log(chalk.gray(
@@ -652,7 +655,14 @@ export async function updateCommand(options) {
652
655
  ` ${(msg.droppedForeignCommandHashes || 'Dropped {count} command record(s) for commands UDS does not ship.').replace('{count}', foreignCommandsOnLatest.length)}`
653
656
  ));
654
657
  }
655
- if (retiredOnLatest.length > 0 || foreignSkillsOnLatest.length > 0 || foreignCommandsOnLatest.length > 0) {
658
+ if (foreignNamesOnLatest > 0) {
659
+ console.log();
660
+ console.log(chalk.gray(
661
+ ` ${(msg.droppedForeignNames || 'Dropped {count} skill/command name(s) from the manifest that UDS does not ship or that are not installed.').replace('{count}', foreignNamesOnLatest)}`
662
+ ));
663
+ }
664
+ if (retiredOnLatest.length > 0 || foreignSkillsOnLatest.length > 0 || foreignCommandsOnLatest.length > 0
665
+ || foreignNamesOnLatest > 0) {
656
666
  writeManifest(manifest, projectPath);
657
667
  }
658
668
 
@@ -1657,23 +1667,11 @@ export async function updateCommand(options) {
1657
1667
  console.log(chalk.gray(` ${msg.updateViaMarketplace}`));
1658
1668
  console.log(chalk.gray(` • ${msg.autoUpdate}`));
1659
1669
  console.log(chalk.gray(` • ${msg.manualUpdate}`));
1660
- } else if (location === 'user') {
1661
- console.log(chalk.yellow(` ${msg.manualInstallDeprecated}`));
1662
- console.log(chalk.gray(` ${msg.recommendedMigrate}`));
1663
- console.log(chalk.gray(' /plugin add https://github.com/anthropics/claude-code-plugins/blob/main/skills/universal-dev-standards.md'));
1664
- console.log(chalk.gray(` ${msg.orUpdateManually}`));
1665
- console.log(chalk.gray(' cd ~/.claude/skills/universal-dev-standards && git pull'));
1666
- } else if (location === 'project') {
1667
- console.log(chalk.yellow(` ${msg.manualInstallDeprecated}`));
1668
- console.log(chalk.gray(` ${msg.recommendedMigrate}`));
1669
- console.log(chalk.gray(' /plugin add https://github.com/anthropics/claude-code-plugins/blob/main/skills/universal-dev-standards.md'));
1670
- console.log(chalk.gray(` ${msg.orUpdateManually}`));
1671
- console.log(chalk.gray(' cd .claude/skills/universal-dev-standards && git pull'));
1672
1670
  } else {
1673
- // Legacy or unknown installation
1674
- console.log(chalk.yellow(` ${msg.manualInstallDeprecated}`));
1675
- console.log(chalk.gray(` ${msg.recommendedMigrate}`));
1676
- console.log(chalk.gray(' /plugin add https://github.com/anthropics/claude-code-plugins/blob/main/skills/universal-dev-standards.md'));
1671
+ // XSPEC-462 R1: project level, user level or not known: one way to update them. This used to call
1672
+ // them "deprecated" and point at a generic plugin URL and a `git pull` in the skills folder; neither
1673
+ // is how UDS installs or updates skills (`uds update --apply --skills` is).
1674
+ console.log(chalk.gray(` ${msg.skillsUpdateCommand}`));
1677
1675
  }
1678
1676
  }
1679
1677
  }
@@ -2928,6 +2926,15 @@ async function updateSkillsOnly(projectPath, manifest, options) {
2928
2926
  // XSPEC-454 R2: and forget the records that were never UDS's (the manifest this merges into
2929
2927
  // may come from an installer that hashed the whole skills folder).
2930
2928
  pruneForeignSkillHashes(manifest);
2929
+ // XSPEC-456 R4: and the names UDS cannot vouch for (not shipped, or not on disk where installed).
2930
+ const skillNamesBefore = manifest.skills.names.length;
2931
+ pruneForeignSkillNames(manifest, projectPath, { checkDisk: true });
2932
+ const droppedSkillNames = skillNamesBefore - manifest.skills.names.length;
2933
+ if (droppedSkillNames > 0) {
2934
+ console.log(chalk.gray(
2935
+ ` ${(msg.droppedForeignNames || 'Dropped {count} skill/command name(s) from the manifest that UDS does not ship or that are not installed.').replace('{count}', droppedSkillNames)}`
2936
+ ));
2937
+ }
2931
2938
 
2932
2939
  // 🔴 Re-read before writing. `manifest` was loaded at the top of the update
2933
2940
  // command, BEFORE the reconciler ran; the reconciler writes its own copy to
@@ -2952,6 +2959,9 @@ async function updateSkillsOnly(projectPath, manifest, options) {
2952
2959
  finishStepBackup(projectPath, skillsBackup);
2953
2960
 
2954
2961
  console.log();
2962
+ // XSPEC-465 R1: a personal skill with the same name as one of the UDS skills just written wins silently.
2963
+ // Information only: it does not change what was installed or the exit code.
2964
+ printSkillNameCollisionWarning(projectPath);
2955
2965
  process.exit(0);
2956
2966
  }
2957
2967
 
@@ -3063,6 +3073,15 @@ async function updateCommandsOnly(projectPath, manifest, options) {
3063
3073
  }
3064
3074
  // XSPEC-454 R2: and forget command records for commands UDS does not ship.
3065
3075
  pruneForeignCommandHashes(manifest);
3076
+ // XSPEC-456 R4: same for the command names.
3077
+ const commandNamesBefore = manifest.commands.names.length;
3078
+ pruneForeignCommandNames(manifest, projectPath, { checkDisk: true });
3079
+ const droppedCommandNames = commandNamesBefore - manifest.commands.names.length;
3080
+ if (droppedCommandNames > 0) {
3081
+ console.log(chalk.gray(
3082
+ ` ${(msg.droppedForeignNames || 'Dropped {count} skill/command name(s) from the manifest that UDS does not ship or that are not installed.').replace('{count}', droppedCommandNames)}`
3083
+ ));
3084
+ }
3066
3085
 
3067
3086
  // 🔴 Re-read before writing. `manifest` was loaded at the top of the update
3068
3087
  // command, BEFORE the reconciler ran; the reconciler writes its own copy to
@@ -3498,8 +3517,18 @@ function takeStepBackup(projectPath, label, installations, kind) {
3498
3517
  /** The step is over (its last manifest write is done): record what it created, and say how to undo it. */
3499
3518
  function finishStepBackup(projectPath, backup) {
3500
3519
  finalizeBackup(projectPath, backup.backupId);
3501
- console.log(chalk.gray(` Backup: ${backup.backupId}`));
3520
+ printBackupLocation(backup.backupId);
3521
+ }
3522
+
3523
+ /**
3524
+ * Say where the backup is, how to undo, and what to exclude (XSPEC-456 R7). All backups share one folder,
3525
+ * `.uds-backups/`, so a tool that does not read .gitignore (an indexer, IDE search, grep) can be told to
3526
+ * skip a single name.
3527
+ */
3528
+ function printBackupLocation(backupId) {
3529
+ console.log(chalk.gray(` Backup: ${backupId}`));
3502
3530
  console.log(chalk.gray(' Use `uds update --rollback` to undo.'));
3531
+ console.log(chalk.gray(' Tools that do not read .gitignore (indexers, IDE search, grep): exclude `.uds-backups`.'));
3503
3532
  }
3504
3533
 
3505
3534
  function cleanupBackupsQuietly(projectPath) {
@@ -3560,7 +3589,7 @@ async function handleRollback(projectPath) {
3560
3589
  console.log(chalk.red('Rollback did NOT complete. The project may be in a mixed state:'));
3561
3590
  printPaths('✗', result.errors, 30, chalk.red);
3562
3591
  console.log(chalk.yellow(' What to do: fix the cause above (permissions, a locked file) and run `uds update --rollback` again —'));
3563
- console.log(chalk.yellow(' it is safe to repeat. The backups are still in .uds-backup-* if you need to copy files back by hand.'));
3592
+ console.log(chalk.yellow(' it is safe to repeat. The backups are still in .uds-backups/ (and .uds-backup-* if an older UDS made them) if you need to copy files back by hand.'));
3564
3593
  }
3565
3594
  if ((result.notRestored || []).length > 0) {
3566
3595
  console.log(chalk.yellow('Not restored:'));
@@ -3577,10 +3606,10 @@ async function handleRollback(projectPath) {
3577
3606
  /**
3578
3607
  * Handle --plan: show what the reconciler would do without executing.
3579
3608
  */
3580
- async function handlePlan(projectPath, options, manifest) {
3609
+ async function handlePlan(projectPath, options, manifest, addStandards = []) {
3581
3610
  const spinner = createSpinner('Calculating reconciliation plan...').start();
3582
3611
 
3583
- const result = await reconcilerPlan(projectPath, { force: false });
3612
+ const result = await reconcilerPlan(projectPath, { force: false, addStandards });
3584
3613
 
3585
3614
  spinner.stop();
3586
3615
 
@@ -3608,10 +3637,17 @@ async function handlePlan(projectPath, options, manifest) {
3608
3637
  // the plan above were silently skipped; the files were still on disk
3609
3638
  // afterwards. Nor is `--force` the answer for "apply what I just read": it
3610
3639
  // recomputes with force:true, a larger plan that rewrites every managed file.
3611
- console.log(chalk.gray('Run `uds update --apply` to apply exactly these changes.'));
3640
+ // A plan made with --add-standard is only applied exactly by an --apply that names the same standards.
3641
+ const addFlags = addStandards.map(id => ` --add-standard ${id}`).join('');
3642
+ console.log(chalk.gray(`Run \`uds update --apply${addFlags}\` to apply exactly these changes.`));
3612
3643
  console.log(chalk.gray('Run `uds update --force` to rewrite every managed file (a larger plan than the one above).'));
3613
3644
  console.log();
3614
3645
  }
3646
+
3647
+ // XSPEC-458 R2: what UDS ships that this project does not have. Information only — it is printed after
3648
+ // the plan is final and nothing above reads it.
3649
+ printAvailableStandardsSection(result.manifest || manifest, { phase: 'plan' });
3650
+ console.log();
3615
3651
  }
3616
3652
 
3617
3653
  /**
@@ -3625,7 +3661,7 @@ async function handlePlan(projectPath, options, manifest) {
3625
3661
  * @param {Object} options - Command options (uses `yes`)
3626
3662
  * @param {{ force: boolean }} mode
3627
3663
  */
3628
- async function handleReconcile(projectPath, options, { force }) {
3664
+ async function handleReconcile(projectPath, options, { force, addStandards = [] }) {
3629
3665
  console.log(chalk.cyan(
3630
3666
  force
3631
3667
  ? 'Running declarative state reconciliation (force mode)...'
@@ -3634,7 +3670,7 @@ async function handleReconcile(projectPath, options, { force }) {
3634
3670
  console.log();
3635
3671
 
3636
3672
  // First show the plan
3637
- const planResult = await reconcilerPlan(projectPath, { force });
3673
+ const planResult = await reconcilerPlan(projectPath, { force, addStandards });
3638
3674
 
3639
3675
  if (planResult.plan.actions.length === 0) {
3640
3676
  // XSPEC-454 R2: nothing to apply, but the manifest may still list skill files UDS never installed
@@ -3642,6 +3678,8 @@ async function handleReconcile(projectPath, options, { force }) {
3642
3678
  const current = readManifest(projectPath);
3643
3679
  if (current && (pruneForeignSkillHashes(current).length + pruneForeignCommandHashes(current).length) > 0) writeManifest(current, projectPath);
3644
3680
  console.log(chalk.green('Everything is up to date. No changes needed.'));
3681
+ // XSPEC-458 R2: "up to date" is about the files UDS manages; say what UDS ships that is not managed here.
3682
+ printAvailableStandardsSection(planResult.manifest, { phase: 'apply' });
3645
3683
  console.log();
3646
3684
  return;
3647
3685
  }
@@ -3668,6 +3706,7 @@ async function handleReconcile(projectPath, options, { force }) {
3668
3706
  const result = await reconcile(projectPath, {
3669
3707
  force,
3670
3708
  backup: true,
3709
+ addStandards,
3671
3710
  onAction: (action, index, total) => {
3672
3711
  spinner.text = `[${index + 1}/${total}] ${action.type} ${action.path || action.category}`;
3673
3712
  }
@@ -3680,8 +3719,7 @@ async function handleReconcile(projectPath, options, { force }) {
3680
3719
  }
3681
3720
 
3682
3721
  if (result.execution?.backupId) {
3683
- console.log(chalk.gray(` Backup: ${result.execution.backupId}`));
3684
- console.log(chalk.gray(' Use `uds update --rollback` to undo.'));
3722
+ printBackupLocation(result.execution.backupId);
3685
3723
  }
3686
3724
 
3687
3725
  if (result.errors.length > 0) {
@@ -3692,5 +3730,7 @@ async function handleReconcile(projectPath, options, { force }) {
3692
3730
  }
3693
3731
  }
3694
3732
 
3733
+ // XSPEC-458 R2: the count of what UDS ships and this project lacks, with the command that installs one.
3734
+ printAvailableStandardsSection(result.manifest || planResult.manifest, { phase: 'apply' });
3695
3735
  console.log();
3696
3736
  }
@@ -851,11 +851,10 @@ export function areCommandsInstalled(manifest) {
851
851
  return manifest.commands?.installed || false;
852
852
  }
853
853
 
854
- /**
855
- * Placeholder stored in `skills.names` when skills come from the Claude Code
856
- * plugin marketplace rather than being copied into the project.
857
- */
858
- export const MARKETPLACE_NAMES_SENTINEL = 'all-via-plugin';
854
+ // Placeholder stored in `skills.names` when skills come from the Claude Code plugin marketplace.
855
+ // It lives in its own module so the name-ownership code can read it without loading this whole module.
856
+ export { MARKETPLACE_NAMES_SENTINEL } from './marketplace-sentinel.js';
857
+ import { MARKETPLACE_NAMES_SENTINEL } from './marketplace-sentinel.js';
859
858
 
860
859
  /**
861
860
  * Merge the names actually installed by a run into a manifest name list.
@@ -872,11 +871,14 @@ export const MARKETPLACE_NAMES_SENTINEL = 'all-via-plugin';
872
871
  * update.js and config.js, and a private copy per module is how the writers drift
873
872
  * apart again.
874
873
  *
875
- * It only ever adds. A name recorded by an older UDS version that no longer ships
876
- * (machine-setup still lists `methodology-system`, plus five non-skill directories
877
- * an old deny-list bug misfiled as skills) stays in the list. Pruning would need
878
- * to know the name is absent for *every* agent, and over-reporting is harmless
879
- * now that the reconciler derives desired state from the shipped set instead.
874
+ * This function only ever adds; removing is a separate step done right after it
875
+ * (XSPEC-456 R4, `utils/installed-names-ownership.js`). The earlier version of this
876
+ * comment said pruning was unnecessary because "over-reporting is harmless" - it is
877
+ * not: after an update removed the five non-skill directories an old deny-list bug
878
+ * had misfiled as skills (`_shared`, `agents`, `ai`, `tools`, `workflows`), the
879
+ * manifest still named them as installed skills, next to a `skillHashes` that had
880
+ * been cleaned. A name that UDS does not ship, or that is not on disk where it was
881
+ * installed, is dropped by `uds update`.
880
882
  *
881
883
  * @param {string[]} existing - Current manifest list
882
884
  * @param {Object} installResult - Result from installSkills/CommandsToMultipleAgents
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Placeholder stored in `skills.names` when skills come from the Claude Code
3
+ * plugin marketplace rather than being copied into the project.
4
+ */
5
+ export const MARKETPLACE_NAMES_SENTINEL = 'all-via-plugin';
@@ -0,0 +1,103 @@
1
+ /**
2
+ * What an adopting project declares for `uds open-work`, read from the `open_work` section of
3
+ * uds.project.yaml (dev-platform XSPEC-460 R4 and XSPEC-461 R2: one namespace for both).
4
+ *
5
+ * version: "1"
6
+ * open_work:
7
+ * projects: # logical project name -> where it lives on THIS machine
8
+ * uds: ../universal-dev-standards
9
+ * vibeops: ../vibeops
10
+ * next_action_words: # extra words that mean "next action" in this project's carriers
11
+ * - 待辦
12
+ * command_words: # extra program names read as a command in a next action or a draft
13
+ * - kubectl
14
+ *
15
+ * This file holds no rule. It turns the section into the same `--root NAME=DIR` and
16
+ * `--next-action-word WORD` arguments a person could type, and hands them to the checker, which
17
+ * is self-contained (node builtins only) and therefore cannot read YAML itself. The repository
18
+ * shim `node scripts/check-open-work-tracking.mjs` does not read uds.project.yaml: it takes the
19
+ * flags only.
20
+ *
21
+ * Directories are resolved against the directory holding uds.project.yaml. A relative path keeps
22
+ * the committed file free of a user name and valid on every machine that lays the projects out
23
+ * the same way; an absolute path works but is the machine-specific thing OWT-027 keeps out of a
24
+ * carrier, so it belongs in a file that is not committed.
25
+ *
26
+ * @module core/open-work-config
27
+ */
28
+
29
+ import { resolve, isAbsolute } from 'path';
30
+ import { loadProjectConfig, CONFIG_FILENAME } from './project-config.js';
31
+ import { PROJECT_NAME } from '../utils/open-work-tracking.mjs';
32
+
33
+ /**
34
+ * @returns {{projects: Object<string,string>, nextActionWords: string[], note: string|null, error: string|null}}
35
+ * `note`: the file exists but could not be read at all (nothing was applied; the command goes on).
36
+ * `error`: the file is readable and its open_work section is wrong (the command stops with exit 2).
37
+ */
38
+ export function readOpenWorkDeclarations(cwd = process.cwd()) {
39
+ const out = { projects: {}, nextActionWords: [], commandWords: [], note: null, error: null };
40
+ let config;
41
+ try {
42
+ config = loadProjectConfig(cwd);
43
+ } catch (e) {
44
+ out.note = `${CONFIG_FILENAME} could not be read (${String(e.message).split('\n')[0]}); the open_work declarations in it were not applied`;
45
+ return out;
46
+ }
47
+ const section = config ? config.open_work : undefined;
48
+ if (section === undefined) return out;
49
+ const bad = (why) => { out.error = `${CONFIG_FILENAME}: open_work ${why}`; return out; };
50
+ if (typeof section !== 'object' || Array.isArray(section)) return bad('must be a mapping with projects and next_action_words');
51
+
52
+ if (section.projects !== undefined && section.projects !== null) {
53
+ if (typeof section.projects !== 'object' || Array.isArray(section.projects)) return bad('.projects must be a mapping of project name to directory');
54
+ for (const [name, dir] of Object.entries(section.projects)) {
55
+ if (!PROJECT_NAME.test(name)) return bad(`.projects: "${name}" is not a logical project name (lower-case letters, digits, "-" and "_", starting with a letter, 2 to 32 characters)`);
56
+ if (typeof dir !== 'string' || dir.trim() === '') return bad(`.projects.${name} must be a directory, written as text`);
57
+ out.projects[name] = isAbsolute(dir) ? dir : resolve(cwd, dir);
58
+ }
59
+ }
60
+ if (section.next_action_words !== undefined && section.next_action_words !== null) {
61
+ if (!Array.isArray(section.next_action_words)) return bad('.next_action_words must be a list of words');
62
+ for (const w of section.next_action_words) {
63
+ if (typeof w !== 'string') return bad('.next_action_words must hold text only; write each word as plain text');
64
+ out.nextActionWords.push(w);
65
+ }
66
+ }
67
+ if (section.command_words !== undefined && section.command_words !== null) {
68
+ if (!Array.isArray(section.command_words)) return bad('.command_words must be a list of program names');
69
+ for (const w of section.command_words) {
70
+ if (typeof w !== 'string') return bad('.command_words must hold text only; write each program name as plain text');
71
+ out.commandWords.push(w);
72
+ }
73
+ }
74
+ return out;
75
+ }
76
+
77
+ /**
78
+ * The `--root` arguments for `uds open-work waiting`: what was typed (a plain DIR, and NAME=DIR for other
79
+ * projects), then every project the file declares that was not already named on the command line (the command
80
+ * line wins for a name given in both).
81
+ */
82
+ export function rootArguments(cliRoots, declaredProjects = {}) {
83
+ const given = [].concat(cliRoots ?? []);
84
+ const named = new Set(given.map((v) => /^([^\s/\\=]+)=/.exec(String(v))?.[1]).filter(Boolean));
85
+ const argv = [];
86
+ for (const [name, dir] of Object.entries(declaredProjects)) if (!named.has(name)) argv.push('--root', `${name}=${dir}`);
87
+ for (const v of given) argv.push('--root', v);
88
+ return argv;
89
+ }
90
+
91
+ /** The `--command-word` arguments, merged the same way. */
92
+ export function commandArguments(cliWords, declaredWords = []) {
93
+ const argv = [];
94
+ for (const w of [].concat(cliWords ?? [], declaredWords)) argv.push('--command-word', w);
95
+ return argv;
96
+ }
97
+
98
+ /** The `--next-action-word` arguments: the command line's words, then the file's. Merged, never either-or. */
99
+ export function wordArguments(cliWords, declaredWords = []) {
100
+ const argv = [];
101
+ for (const w of [].concat(cliWords ?? [], declaredWords)) argv.push('--next-action-word', w);
102
+ return argv;
103
+ }
@@ -4,13 +4,23 @@
4
4
  */
5
5
  import { existsSync, readFileSync } from 'fs';
6
6
  import { join } from 'path';
7
+ import * as yaml from 'js-yaml';
7
8
 
8
9
  const CONFIG_FILENAME = 'uds.project.yaml';
9
10
 
11
+ /** Sections whose entries are `intent: command` pairs. */
12
+ const COMMAND_SECTIONS = ['commands', 'custom'];
13
+
10
14
  /**
11
15
  * Parse uds.project.yaml from the given project path.
12
16
  * Returns null if the file does not exist.
13
17
  * Throws if the file exists but is invalid.
18
+ *
19
+ * XSPEC-456 R1: the file is read as YAML. It used to go through a hand-written line parser that
20
+ * kept everything after the first colon as the value, so a trailing comment
21
+ * (`test: dotnet test X.csproj # 90 tests pass`) became part of the command. A POSIX shell hides
22
+ * that (an unquoted `#` starts a comment), `cmd.exe` does not - the comment reached MSBuild as
23
+ * arguments. Reading the value the way YAML defines it removes the comment before anything is run.
14
24
  */
15
25
  export function loadProjectConfig(projectPath = '.') {
16
26
  const configPath = join(projectPath, CONFIG_FILENAME);
@@ -18,55 +28,64 @@ export function loadProjectConfig(projectPath = '.') {
18
28
 
19
29
  const raw = readFileSync(configPath, 'utf8');
20
30
 
21
- // Minimal YAML parser for the simple key: value structure we need.
22
- // We deliberately avoid a heavy dependency — uds.project.yaml is intentionally simple.
23
- const config = parseMinimalYaml(raw, configPath);
31
+ const config = parseProjectYaml(raw, configPath);
24
32
  validateConfig(config, configPath);
25
33
  return config;
26
34
  }
27
35
 
28
36
  /**
29
- * Parse a minimal YAML subset sufficient for uds.project.yaml.
30
- * Supports: top-level scalars, one-level nested mappings (commands:, custom:).
37
+ * Parse the file with a real YAML parser and normalise it to the shape callers use:
38
+ * top-level scalars and the `commands` / `custom` sections are strings.
31
39
  */
32
- function parseMinimalYaml(raw, _filePath) {
33
- const lines = raw.split('\n');
34
- const result = {};
35
- let currentSection = null;
36
-
37
- for (let i = 0; i < lines.length; i++) {
38
- const line = lines[i];
39
- const trimmed = line.trimEnd();
40
-
41
- // Skip blank lines and comments
42
- if (!trimmed || trimmed.trimStart().startsWith('#')) continue;
43
-
44
- const indent = line.length - line.trimStart().length;
40
+ function parseProjectYaml(raw, filePath) {
41
+ let doc;
42
+ try {
43
+ doc = yaml.load(raw);
44
+ } catch (err) {
45
+ const line = err?.mark ? ` (line ${err.mark.line + 1})` : '';
46
+ const reason = err?.reason || err?.message || String(err);
47
+ // A double-quoted YAML value reads backslashes as escapes. Windows paths written that way
48
+ // used to work (the old parser kept them verbatim), so say what to do instead of only failing.
49
+ const hint = /escape|hexadecimal/i.test(reason)
50
+ ? ' Inside double quotes a backslash starts an escape sequence; write Windows paths in single quotes or without quotes.'
51
+ : '';
52
+ throw new Error(`${filePath}: not valid YAML${line}: ${reason}.${hint}`);
53
+ }
54
+ if (doc === null || doc === undefined) return {};
55
+ if (typeof doc !== 'object' || Array.isArray(doc)) {
56
+ throw new Error(`${filePath}: the file must be a mapping of keys to values.`);
57
+ }
45
58
 
46
- if (indent === 0) {
47
- // Top-level key
48
- const match = trimmed.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/);
49
- if (!match) continue;
50
- const [, key, value] = match;
51
- if (value.trim()) {
52
- result[key] = value.trim().replace(/^["']|["']$/g, '');
53
- currentSection = null;
54
- } else {
55
- result[key] = {};
56
- currentSection = key;
57
- }
58
- } else if (currentSection && indent > 0) {
59
- // Nested key under current section
60
- const match = trimmed.trim().match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*)$/);
61
- if (!match) continue;
62
- const [, key, value] = match;
63
- result[currentSection][key] = value.trim().replace(/^["']|["']$/g, '');
59
+ const result = {};
60
+ for (const [key, value] of Object.entries(doc)) {
61
+ if (COMMAND_SECTIONS.includes(key)) {
62
+ result[key] = normaliseCommandSection(key, value, filePath);
63
+ } else if (value !== null && typeof value === 'object') {
64
+ result[key] = value;
65
+ } else if (value !== null && value !== undefined) {
66
+ result[key] = String(value);
64
67
  }
65
68
  }
66
-
67
69
  return result;
68
70
  }
69
71
 
72
+ function normaliseCommandSection(name, value, filePath) {
73
+ if (value === null || value === undefined) return {};
74
+ if (typeof value !== 'object' || Array.isArray(value)) {
75
+ throw new Error(`${filePath}: "${name}" must be a mapping of intent: command pairs.`);
76
+ }
77
+ const out = {};
78
+ for (const [intent, command] of Object.entries(value)) {
79
+ if (command === null || command === undefined) continue;
80
+ if (typeof command === 'object') {
81
+ throw new Error(`${filePath}: "${name}.${intent}" must be a single command string, not a list or mapping.`);
82
+ }
83
+ const text = String(command).trim();
84
+ if (text) out[intent] = text;
85
+ }
86
+ return out;
87
+ }
88
+
70
89
  function validateConfig(config, filePath) {
71
90
  if (!config.version) {
72
91
  throw new Error(
@@ -85,7 +104,8 @@ function validateConfig(config, filePath) {
85
104
  */
86
105
  export function getCommand(config, intent) {
87
106
  if (!config) return undefined;
88
- return config.commands?.[intent] ?? config.custom?.[intent];
107
+ const own = (section) => (section && Object.prototype.hasOwnProperty.call(section, intent) ? section[intent] : undefined);
108
+ return own(config.commands) ?? own(config.custom);
89
109
  }
90
110
 
91
111
  export { CONFIG_FILENAME };
@@ -139,6 +139,16 @@ export async function runInitFlow(options, detected, projectPath) {
139
139
 
140
140
  const installations = await promptSkillsInstallLocation(aiTools);
141
141
 
142
+ // XSPEC-468 R1: the project way is pre-selected, so an empty answer was a deliberate "no". Say what that
143
+ // means (nothing is written to the project) and where the skills can come from instead.
144
+ if (installations.length === 0) {
145
+ console.log();
146
+ console.log(chalk.yellow(msgAfterLang.skillsSkippedTitle));
147
+ for (const line of msgAfterLang.skillsFromPluginLines) {
148
+ console.log(chalk.gray(` ${line}`));
149
+ }
150
+ }
151
+
142
152
  if (installations.length > 0) {
143
153
  const isMarketplace = installations.some(i => i.level === 'marketplace');
144
154