universal-dev-standards 6.14.0-beta.4 → 6.14.0-beta.6

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 (56) hide show
  1. package/bin/uds.js +9 -2
  2. package/bundled/ai/standards/commit-message.ai.yaml +6 -2
  3. package/bundled/ai/standards/full-coverage-testing.ai.yaml +46 -5
  4. package/bundled/core/full-coverage-testing.md +57 -3
  5. package/bundled/locales/zh-CN/CHANGELOG.md +54 -3
  6. package/bundled/locales/zh-CN/README.md +1 -1
  7. package/bundled/locales/zh-CN/SECURITY.md +1 -1
  8. package/bundled/locales/zh-CN/core/full-coverage-testing.md +61 -7
  9. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +4 -2
  10. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +10 -6
  11. package/bundled/locales/zh-TW/CHANGELOG.md +54 -3
  12. package/bundled/locales/zh-TW/README.md +1 -1
  13. package/bundled/locales/zh-TW/SECURITY.md +1 -1
  14. package/bundled/locales/zh-TW/core/full-coverage-testing.md +61 -7
  15. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +4 -2
  16. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +10 -6
  17. package/bundled/templates/gates/check-anti-fake-tests.mjs +991 -0
  18. package/bundled/templates/gates/check-stubs.mjs +644 -0
  19. package/package.json +2 -2
  20. package/src/commands/audit.js +11 -0
  21. package/src/commands/check.js +124 -24
  22. package/src/commands/deps.js +31 -1
  23. package/src/commands/init.js +16 -0
  24. package/src/commands/simulate.js +20 -8
  25. package/src/commands/skills.js +42 -2
  26. package/src/commands/spec.js +14 -8
  27. package/src/commands/update.js +222 -21
  28. package/src/core/install-records.js +2 -1
  29. package/src/core/manifest.js +12 -10
  30. package/src/core/marketplace-sentinel.js +5 -0
  31. package/src/core/project-config.js +58 -38
  32. package/src/i18n/messages.js +77 -9
  33. package/src/reconciler/backup-locations.js +75 -0
  34. package/src/reconciler/backup-manager.js +435 -115
  35. package/src/reconciler/index.js +44 -5
  36. package/src/reconciler/install-roots.js +90 -0
  37. package/src/reconciler/plan-executor.js +23 -2
  38. package/src/uninstallers/hook-uninstaller.js +2 -1
  39. package/src/utils/command-hash-ownership.js +103 -0
  40. package/src/utils/commit-message-judge.js +137 -0
  41. package/src/utils/copier.js +21 -1
  42. package/src/utils/deps-applicability.js +25 -0
  43. package/src/utils/gate-scripts.js +141 -0
  44. package/src/utils/health-scorer.js +10 -7
  45. package/src/utils/installed-names-ownership.js +114 -0
  46. package/src/utils/sdd-header.js +65 -0
  47. package/src/utils/skill-hash-ownership.js +64 -0
  48. package/src/utils/skills-installer.js +12 -1
  49. package/src/utils/standard-validator.js +98 -27
  50. package/src/utils/test-change-check.js +160 -0
  51. package/src/utils/test-policy.js +214 -0
  52. package/src/utils/update-summary.js +29 -0
  53. package/src/vibe/micro-spec.js +15 -0
  54. package/standards-registry.json +7 -7
  55. package/bundled/extensions/languages/php/fat-free-patterns.md +0 -915
  56. package/bundled/extensions/languages/php/php-style.md +0 -693
@@ -25,6 +25,10 @@ import {
25
25
  getToolFromPath
26
26
  } from '../utils/reference-sync.js';
27
27
  import { checkForUpdates } from '../utils/npm-registry.js';
28
+ import { pruneForeignSkillHashes } from '../utils/skill-hash-ownership.js';
29
+ import { pruneForeignCommandHashes } from '../utils/command-hash-ownership.js';
30
+ import { pruneForeignSkillNames, pruneForeignCommandNames } from '../utils/installed-names-ownership.js';
31
+ import { commandsUpdatedMessage } from '../utils/update-summary.js';
28
32
  import { t, setLanguage, isLanguageExplicitlySet } from '../i18n/messages.js';
29
33
  import { config } from '../utils/config-manager.js';
30
34
  import {
@@ -47,7 +51,8 @@ import {
47
51
  import { getMarketplaceSkillsInfo } from '../utils/github.js';
48
52
  import { detectAITools } from '../utils/detector.js';
49
53
  import { HOOK_CAPABLE_TOOLS, resolveHookTools, installMissingHooks } from '../installers/hooks-installer.js';
50
- import { persistRecorder, mergeRecorderInto } from '../core/install-records.js';
54
+ import { persistRecorder, mergeRecorderInto, newRecorder } from '../core/install-records.js';
55
+ import { installGateScripts, gateStandardInstalled, GATE_SCRIPTS } from '../utils/gate-scripts.js';
51
56
  import { migrateLegacyHuskyHook } from '../utils/legacy-hook-migration.js';
52
57
  import {
53
58
  promptSkillsInstallLocation,
@@ -58,8 +63,12 @@ import {
58
63
  plan as reconcilerPlan,
59
64
  rollbackLast,
60
65
  formatPlan,
61
- listBackups
66
+ listBackups,
67
+ createStepBackup,
68
+ finalizeBackup,
69
+ cleanupBackups
62
70
  } from '../reconciler/index.js';
71
+ import { stepWritePaths } from '../reconciler/install-roots.js';
63
72
  import { restoreSingleFile } from './check.js';
64
73
  import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
65
74
  import { resolveIntegrationFile, SUPPORTED_AI_TOOLS, getToolFormat } from '../core/constants.js';
@@ -619,6 +628,15 @@ export async function updateCommand(options) {
619
628
  // definition — telling them to run `uds update --prune` and then returning
620
629
  // before anything is examined is how the complaint became unclearable.
621
630
  const retiredOnLatest = pruneRetiredHashes(manifest, projectPath);
631
+ // XSPEC-454 R2: skill records UDS never owned go the same way (an up-to-date adopter is exactly the
632
+ // one who has nothing else to trigger the correction).
633
+ const foreignSkillsOnLatest = pruneForeignSkillHashes(manifest);
634
+ const foreignCommandsOnLatest = pruneForeignCommandHashes(manifest);
635
+ // XSPEC-456 R4: and the skill / command NAME lists (same reason).
636
+ const namesOnLatestBefore = (manifest.skills?.names?.length ?? 0) + (manifest.commands?.names?.length ?? 0);
637
+ pruneForeignSkillNames(manifest, projectPath);
638
+ pruneForeignCommandNames(manifest, projectPath);
639
+ const foreignNamesOnLatest = namesOnLatestBefore - (manifest.skills?.names?.length ?? 0) - (manifest.commands?.names?.length ?? 0);
622
640
  if (retiredOnLatest.length > 0) {
623
641
  console.log();
624
642
  console.log(chalk.gray(
@@ -627,6 +645,27 @@ export async function updateCommand(options) {
627
645
  for (const path of retiredOnLatest) {
628
646
  console.log(chalk.gray(` - ${path}`));
629
647
  }
648
+ }
649
+ if (foreignSkillsOnLatest.length > 0) {
650
+ console.log();
651
+ console.log(chalk.gray(
652
+ ` ${(msg.droppedForeignSkillHashes || 'Dropped {count} skill record(s) that do not describe files UDS installed.').replace('{count}', foreignSkillsOnLatest.length)}`
653
+ ));
654
+ }
655
+ if (foreignCommandsOnLatest.length > 0) {
656
+ console.log();
657
+ console.log(chalk.gray(
658
+ ` ${(msg.droppedForeignCommandHashes || 'Dropped {count} command record(s) for commands UDS does not ship.').replace('{count}', foreignCommandsOnLatest.length)}`
659
+ ));
660
+ }
661
+ if (foreignNamesOnLatest > 0) {
662
+ console.log();
663
+ console.log(chalk.gray(
664
+ ` ${(msg.droppedForeignNames || 'Dropped {count} skill/command name(s) from the manifest that UDS does not ship or that are not installed.').replace('{count}', foreignNamesOnLatest)}`
665
+ ));
666
+ }
667
+ if (retiredOnLatest.length > 0 || foreignSkillsOnLatest.length > 0 || foreignCommandsOnLatest.length > 0
668
+ || foreignNamesOnLatest > 0) {
630
669
  writeManifest(manifest, projectPath);
631
670
  }
632
671
 
@@ -1139,7 +1178,7 @@ export async function updateCommand(options) {
1139
1178
  manifest.options.coverage_model = manifest.options.coverage_model || 'full-coverage';
1140
1179
  console.log();
1141
1180
  console.log(chalk.yellow(msg.testParadigmMigrated || '⚠ Testing paradigm migrated: pyramid thresholds (UT≥80%/IT≥70%) → behavior-completeness full coverage (XSPEC-178)'));
1142
- console.log(chalk.cyan(msg.testParadigmNote || ' full-coverage-testing.ai.yaml installed. Review scripts/check-stubs.sh and scripts/check-anti-fake-tests.sh in your project.'));
1181
+ console.log(chalk.cyan(msg.testParadigmNote || ' full-coverage-testing.ai.yaml installed. Review scripts/check-stubs.mjs and scripts/check-anti-fake-tests.mjs in your project (`uds update` offers to write them).'));
1143
1182
  }
1144
1183
 
1145
1184
  // Update manifest
@@ -1657,6 +1696,9 @@ export async function updateCommand(options) {
1657
1696
  // 錯誤訊息單一出口閘門:問過才寫,而且從不覆寫。
1658
1697
  await offerErrorExitGate(projectPath, options);
1659
1698
 
1699
+ // 假測試與空殼掃描(XSPEC-444 R5):同樣問過才寫、從不覆寫。
1700
+ await offerTestQualityGates(projectPath, options);
1701
+
1660
1702
  // Exit explicitly to prevent hanging.
1661
1703
  // T11: a partial update exits non-zero so CI / scripts can detect the failure.
1662
1704
  process.exit(updateIncomplete ? 1 : 0);
@@ -1706,6 +1748,47 @@ async function offerErrorExitGate(projectPath, options) {
1706
1748
  console.log();
1707
1749
  }
1708
1750
 
1751
+ /**
1752
+ * Offer the fake-test and stub scanners to an EXISTING installation.
1753
+ * // implements XSPEC-444 R5
1754
+ *
1755
+ * `uds init` writes them for a new project. A project initialised before that has the
1756
+ * full-coverage-testing standard — which asks for these two scripts — but never received them.
1757
+ * Writing files into a repository nobody asked us to touch is a trust problem, so this shows
1758
+ * what is about to be written, asks (default: no), and never overwrites a file that exists.
1759
+ */
1760
+ async function offerTestQualityGates(projectPath, options) {
1761
+ if (!gateStandardInstalled(projectPath)) return;
1762
+ const wanted = GATE_SCRIPTS.filter(({ file }) => !existsSync(join(projectPath, 'scripts', file)));
1763
+ if (wanted.length === 0) return;
1764
+ const available = wanted.filter(({ file }) => existsSync(join(getRepoRoot(), 'templates', 'gates', file)));
1765
+ if (available.length === 0) return; // templates not shipped in this package — stay silent, do not pretend
1766
+
1767
+ console.log(chalk.bold(' Fake-test and stub scanners'));
1768
+ console.log(chalk.gray(' The full-coverage-testing standard asks for these scripts; this project does not have them yet:'));
1769
+ for (const { file, what } of available) console.log(chalk.gray(` - scripts/${file} (finds ${what})`));
1770
+ console.log(chalk.gray(' Pure Node, no dependencies. `uds check` runs them and prints what they find as a WARNING;'));
1771
+ console.log(chalk.gray(' nothing is blocked unless you set "mode": "block" in .standards/test-policy.json.'));
1772
+ console.log();
1773
+
1774
+ const ok = await confirmOrFail({
1775
+ message: 'Write these scripts into scripts/ ?',
1776
+ defaultValue: false, // silence is not consent
1777
+ options
1778
+ });
1779
+ if (!ok) {
1780
+ console.log(chalk.gray(' Skipped. `uds check` will mention it again, but never writes them on its own.'));
1781
+ console.log();
1782
+ return;
1783
+ }
1784
+ const recorder = newRecorder();
1785
+ const result = installGateScripts(projectPath, recorder);
1786
+ persistRecorder(projectPath, recorder);
1787
+ for (const rel of result.written) console.log(chalk.green(` ✓ ${rel}`));
1788
+ for (const rel of result.kept) console.log(chalk.gray(` · ${rel} already exists — kept as is`));
1789
+ console.log();
1790
+ }
1791
+
1709
1792
  /**
1710
1793
  * Switch the claude-code integration's target file between CLAUDE.md and
1711
1794
  * CLAUDE.local.md for an EXISTING installation, without a full reinstall.
@@ -2800,6 +2883,16 @@ async function updateSkillsOnly(projectPath, manifest, options) {
2800
2883
  return;
2801
2884
  }
2802
2885
 
2886
+ // XSPEC-454 R1: this step writes outside the reconciler, so it takes its own rollback point — the skill
2887
+ // folders UDS ships, in each project-level skills folder (new ones are created, old ones rewritten, and
2888
+ // `.manifest.json` replaced), and nothing else: the adopter's own skills are not UDS's to roll back.
2889
+ // No backup, no write: an install that cannot be undone must not start.
2890
+ const skillsBackup = takeStepBackup(projectPath, 'skills', fileBasedInstallations, 'skills');
2891
+ if (!skillsBackup.ok) {
2892
+ process.exit(1);
2893
+ return;
2894
+ }
2895
+
2803
2896
  const spinner = createSpinner(msg.installingSkills || 'Installing Skills...').start();
2804
2897
 
2805
2898
  const skillsLocaleForUpdate = resolveLocale(manifest, projectPath, options);
@@ -2845,6 +2938,18 @@ async function updateSkillsOnly(projectPath, manifest, options) {
2845
2938
  if (!manifest.skillHashes) manifest.skillHashes = {};
2846
2939
  Object.assign(manifest.skillHashes, result.allFileHashes);
2847
2940
  }
2941
+ // XSPEC-454 R2: and forget the records that were never UDS's (the manifest this merges into
2942
+ // may come from an installer that hashed the whole skills folder).
2943
+ pruneForeignSkillHashes(manifest);
2944
+ // XSPEC-456 R4: and the names UDS cannot vouch for (not shipped, or not on disk where installed).
2945
+ const skillNamesBefore = manifest.skills.names.length;
2946
+ pruneForeignSkillNames(manifest, projectPath, { checkDisk: true });
2947
+ const droppedSkillNames = skillNamesBefore - manifest.skills.names.length;
2948
+ if (droppedSkillNames > 0) {
2949
+ console.log(chalk.gray(
2950
+ ` ${(msg.droppedForeignNames || 'Dropped {count} skill/command name(s) from the manifest that UDS does not ship or that are not installed.').replace('{count}', droppedSkillNames)}`
2951
+ ));
2952
+ }
2848
2953
 
2849
2954
  // 🔴 Re-read before writing. `manifest` was loaded at the top of the update
2850
2955
  // command, BEFORE the reconciler ran; the reconciler writes its own copy to
@@ -2866,6 +2971,7 @@ async function updateSkillsOnly(projectPath, manifest, options) {
2866
2971
  freshForSkills.skills = manifest.skills;
2867
2972
  freshForSkills.skillHashes = manifest.skillHashes;
2868
2973
  writeManifest(freshForSkills, projectPath);
2974
+ finishStepBackup(projectPath, skillsBackup);
2869
2975
 
2870
2976
  console.log();
2871
2977
  process.exit(0);
@@ -2924,6 +3030,13 @@ async function updateCommandsOnly(projectPath, manifest, options) {
2924
3030
  }
2925
3031
  console.log();
2926
3032
 
3033
+ // XSPEC-454 R1: same as the Skills step — a rollback point first, and no write without one.
3034
+ const commandsBackup = takeStepBackup(projectPath, 'commands', commandsInstallations, 'commands');
3035
+ if (!commandsBackup.ok) {
3036
+ process.exit(1);
3037
+ return;
3038
+ }
3039
+
2927
3040
  const spinner = createSpinner(msg.installingCommands || 'Installing commands...').start();
2928
3041
 
2929
3042
  const commandsLocale = resolveLocale(manifest, projectPath, options);
@@ -2944,9 +3057,8 @@ async function updateCommandsOnly(projectPath, manifest, options) {
2944
3057
  }).join(', ');
2945
3058
 
2946
3059
  if (result.totalErrors === 0) {
2947
- spinner.succeed((msg.commandsUpdated || 'Updated {count} commands: {locations}')
2948
- .replace('{count}', result.totalInstalled)
2949
- .replace('{locations}', locations));
3060
+ // XSPEC-454 R4: tools and commands are different numbers; see commandsUpdatedMessage.
3061
+ spinner.succeed(commandsUpdatedMessage(msg, commandsInstallations, result, locations));
2950
3062
  } else {
2951
3063
  spinner.warn((msg.commandsUpdatedWithErrors || 'Updated commands with {errors} errors')
2952
3064
  .replace('{errors}', result.totalErrors));
@@ -2971,6 +3083,17 @@ async function updateCommandsOnly(projectPath, manifest, options) {
2971
3083
  if (!manifest.commandHashes) manifest.commandHashes = {};
2972
3084
  replaceCommandHashesForUpdatedAgents(manifest.commandHashes, result.allFileHashes);
2973
3085
  }
3086
+ // XSPEC-454 R2: and forget command records for commands UDS does not ship.
3087
+ pruneForeignCommandHashes(manifest);
3088
+ // XSPEC-456 R4: same for the command names.
3089
+ const commandNamesBefore = manifest.commands.names.length;
3090
+ pruneForeignCommandNames(manifest, projectPath, { checkDisk: true });
3091
+ const droppedCommandNames = commandNamesBefore - manifest.commands.names.length;
3092
+ if (droppedCommandNames > 0) {
3093
+ console.log(chalk.gray(
3094
+ ` ${(msg.droppedForeignNames || 'Dropped {count} skill/command name(s) from the manifest that UDS does not ship or that are not installed.').replace('{count}', droppedCommandNames)}`
3095
+ ));
3096
+ }
2974
3097
 
2975
3098
  // 🔴 Re-read before writing. `manifest` was loaded at the top of the update
2976
3099
  // command, BEFORE the reconciler ran; the reconciler writes its own copy to
@@ -2994,6 +3117,7 @@ async function updateCommandsOnly(projectPath, manifest, options) {
2994
3117
  freshForCommands.commands = manifest.commands;
2995
3118
  freshForCommands.commandHashes = manifest.commandHashes;
2996
3119
  writeManifest(freshForCommands, projectPath);
3120
+ finishStepBackup(projectPath, commandsBackup);
2997
3121
 
2998
3122
  console.log();
2999
3123
  process.exit(0);
@@ -3386,7 +3510,57 @@ async function promptNewFeatureInstallation(missingSkills, outdatedSkills, missi
3386
3510
  // ─── DSR (Declarative State Reconciliation) Handlers ─────────────
3387
3511
 
3388
3512
  /**
3389
- * Handle --rollback: restore from the most recent backup.
3513
+ * Take the rollback point for a Skills/Commands step (XSPEC-454 R1).
3514
+ * Prints what it did; `ok: false` means the caller must not write anything.
3515
+ */
3516
+ function takeStepBackup(projectPath, label, installations, kind) {
3517
+ const { paths, outside } = stepWritePaths(projectPath, installations, kind);
3518
+ const backup = createStepBackup(projectPath, { label, paths, notBackedUp: outside });
3519
+ if (backup.errors.length > 0) {
3520
+ console.log(chalk.red(`Could not take a backup before updating ${label}; nothing was changed.`));
3521
+ for (const err of backup.errors) console.log(chalk.red(` ${err}`));
3522
+ console.log();
3523
+ return { ok: false };
3524
+ }
3525
+ cleanupBackupsQuietly(projectPath);
3526
+ return { ok: true, backupId: backup.backupId };
3527
+ }
3528
+
3529
+ /** The step is over (its last manifest write is done): record what it created, and say how to undo it. */
3530
+ function finishStepBackup(projectPath, backup) {
3531
+ finalizeBackup(projectPath, backup.backupId);
3532
+ printBackupLocation(backup.backupId);
3533
+ }
3534
+
3535
+ /**
3536
+ * Say where the backup is, how to undo, and what to exclude (XSPEC-456 R7). All backups share one folder,
3537
+ * `.uds-backups/`, so a tool that does not read .gitignore (an indexer, IDE search, grep) can be told to
3538
+ * skip a single name.
3539
+ */
3540
+ function printBackupLocation(backupId) {
3541
+ console.log(chalk.gray(` Backup: ${backupId}`));
3542
+ console.log(chalk.gray(' Use `uds update --rollback` to undo.'));
3543
+ console.log(chalk.gray(' Tools that do not read .gitignore (indexers, IDE search, grep): exclude `.uds-backups`.'));
3544
+ }
3545
+
3546
+ function cleanupBackupsQuietly(projectPath) {
3547
+ try {
3548
+ cleanupBackups(projectPath);
3549
+ } catch {
3550
+ // an old backup that cannot be removed is not a reason to stop the update
3551
+ }
3552
+ }
3553
+
3554
+ /** Print up to `limit` paths, then how many more. */
3555
+ function printPaths(prefix, paths, limit, colour) {
3556
+ for (const p of paths.slice(0, limit)) console.log(colour(` ${prefix} ${p}`));
3557
+ if (paths.length > limit) console.log(colour(` ${prefix} … and ${paths.length - limit} more`));
3558
+ }
3559
+
3560
+ /**
3561
+ * Handle --rollback: undo the newest backup and every earlier one from the same unbroken series of UDS
3562
+ * updates, then say, item by item, what was restored, what was removed, and what was NOT put back.
3563
+ * It never ends in "successful" while any of those lists is not empty (XSPEC-454 R1).
3390
3564
  */
3391
3565
  async function handleRollback(projectPath) {
3392
3566
  const backups = listBackups(projectPath);
@@ -3397,22 +3571,46 @@ async function handleRollback(projectPath) {
3397
3571
  }
3398
3572
 
3399
3573
  const latest = backups[0];
3400
- console.log(chalk.cyan(`Rolling back to: ${latest.backupId}`));
3574
+ console.log(chalk.cyan(`Rolling back from: ${latest.backupId}`));
3401
3575
  console.log(chalk.gray(` Created: ${latest.createdAt}`));
3402
- console.log(chalk.gray(` Actions: ${latest.actionCount}`));
3403
3576
  console.log();
3404
3577
 
3405
3578
  const result = rollbackLast(projectPath);
3406
- if (result.success) {
3407
- console.log(chalk.green(`Rollback successful. Restored ${result.restored.length} files.`));
3408
- for (const file of result.restored) {
3409
- console.log(chalk.gray(` ← ${file}`));
3410
- }
3411
- } else {
3412
- console.log(chalk.red('Rollback failed:'));
3413
- for (const err of result.errors) {
3414
- console.log(chalk.red(` ${err}`));
3415
- }
3579
+
3580
+ for (const step of result.steps || []) {
3581
+ console.log(chalk.cyan(`${step.backupId}${step.label ? ` (${step.label})` : ''}`));
3582
+ console.log(chalk.gray(` Restored ${step.restored.length} file(s), removed ${step.removed.length} file(s) the update had created.`));
3583
+ printPaths('←', step.restored, 12, chalk.gray);
3584
+ printPaths('✕', step.removed, 12, chalk.gray);
3585
+ }
3586
+ if (!result.steps) {
3587
+ // a rollbackLast that predates the step report
3588
+ printPaths('←', result.restored || [], 12, chalk.gray);
3589
+ }
3590
+ console.log();
3591
+
3592
+ if ((result.steps || []).length > 1) {
3593
+ console.log(chalk.gray(` ${result.steps.length} consecutive updates were undone together (each one started from where the previous one ended).`));
3594
+ }
3595
+ if (result.olderBackups > 0) {
3596
+ console.log(chalk.gray(` ${result.olderBackups} older backup(s) are not part of that series (something else changed the project in between) and were left alone.`));
3597
+ }
3598
+
3599
+ if (result.errors.length > 0) {
3600
+ process.exitCode = 1;
3601
+ console.log(chalk.red('Rollback did NOT complete. The project may be in a mixed state:'));
3602
+ printPaths('✗', result.errors, 30, chalk.red);
3603
+ console.log(chalk.yellow(' What to do: fix the cause above (permissions, a locked file) and run `uds update --rollback` again —'));
3604
+ 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.'));
3605
+ }
3606
+ if ((result.notRestored || []).length > 0) {
3607
+ console.log(chalk.yellow('Not restored:'));
3608
+ printPaths('!', result.notRestored, 30, chalk.yellow);
3609
+ }
3610
+ if (result.errors.length === 0 && (result.notRestored || []).length === 0) {
3611
+ console.log(chalk.green(`Rollback successful. Restored ${result.restored.length} file(s), removed ${(result.removed || []).length}.`));
3612
+ } else if (result.errors.length === 0) {
3613
+ console.log(chalk.yellow('Rollback finished for everything inside this project, except the items listed above.'));
3416
3614
  }
3417
3615
  console.log();
3418
3616
  }
@@ -3480,6 +3678,10 @@ async function handleReconcile(projectPath, options, { force }) {
3480
3678
  const planResult = await reconcilerPlan(projectPath, { force });
3481
3679
 
3482
3680
  if (planResult.plan.actions.length === 0) {
3681
+ // XSPEC-454 R2: nothing to apply, but the manifest may still list skill files UDS never installed
3682
+ // (they only ever get corrected by a write, and an up-to-date project has none coming).
3683
+ const current = readManifest(projectPath);
3684
+ if (current && (pruneForeignSkillHashes(current).length + pruneForeignCommandHashes(current).length) > 0) writeManifest(current, projectPath);
3483
3685
  console.log(chalk.green('Everything is up to date. No changes needed.'));
3484
3686
  console.log();
3485
3687
  return;
@@ -3519,8 +3721,7 @@ async function handleReconcile(projectPath, options, { force }) {
3519
3721
  }
3520
3722
 
3521
3723
  if (result.execution?.backupId) {
3522
- console.log(chalk.gray(` Backup: ${result.execution.backupId}`));
3523
- console.log(chalk.gray(' Use `uds update --rollback` to undo.'));
3724
+ printBackupLocation(result.execution.backupId);
3524
3725
  }
3525
3726
 
3526
3727
  if (result.errors.length > 0) {
@@ -26,7 +26,7 @@
26
26
  * }
27
27
  *
28
28
  * `kind` selects what `hash` covers:
29
- * 'hook-script', 'git-hook' → whole file (line endings normalized)
29
+ * 'hook-script', 'gate-script', 'git-hook' → whole file (line endings normalized)
30
30
  * 'integration-file' → everything outside the UDS marker block
31
31
  *
32
32
  * @module core/install-records
@@ -41,6 +41,7 @@ export const RECORDS_KEY = 'installedArtifacts';
41
41
 
42
42
  export const RECORD_KINDS = Object.freeze({
43
43
  HOOK_SCRIPT: 'hook-script',
44
+ GATE_SCRIPT: 'gate-script',
44
45
  GIT_HOOK: 'git-hook',
45
46
  INTEGRATION_FILE: 'integration-file'
46
47
  });
@@ -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';
@@ -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 };