universal-dev-standards 6.14.1-beta.2 → 6.15.0-beta.1

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 (63) hide show
  1. package/bin/uds.js +2 -2
  2. package/bundled/ai/standards/developer-memory.ai.yaml +2 -2
  3. package/bundled/ai/standards/full-coverage-testing.ai.yaml +6 -4
  4. package/bundled/ai/standards/project-context-memory.ai.yaml +2 -2
  5. package/bundled/core/developer-memory.md +1 -1
  6. package/bundled/core/full-coverage-testing.md +4 -2
  7. package/bundled/core/open-work-tracking.md +13 -0
  8. package/bundled/core/project-context-memory.md +1 -1
  9. package/bundled/locales/COVERAGE.md +5 -4
  10. package/bundled/locales/zh-CN/CHANGELOG.md +53 -4
  11. package/bundled/locales/zh-CN/README.md +2 -2
  12. package/bundled/locales/zh-CN/SECURITY.md +3 -3
  13. package/bundled/locales/zh-CN/core/full-coverage-testing.md +5 -3
  14. package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +4 -4
  15. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +1 -0
  16. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +8 -3
  17. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +5 -4
  18. package/bundled/locales/zh-CN/skills/README.md +2 -1
  19. package/bundled/locales/zh-CN/skills/commands/sdd-retro.md +1 -1
  20. package/bundled/locales/zh-CN/skills/dev-workflow-guide/SKILL.md +7 -7
  21. package/bundled/locales/zh-CN/skills/open-work-assistant/SKILL.md +133 -0
  22. package/bundled/locales/zh-TW/CHANGELOG.md +53 -4
  23. package/bundled/locales/zh-TW/README.md +2 -2
  24. package/bundled/locales/zh-TW/SECURITY.md +3 -3
  25. package/bundled/locales/zh-TW/core/developer-memory.md +3 -3
  26. package/bundled/locales/zh-TW/core/full-coverage-testing.md +5 -3
  27. package/bundled/locales/zh-TW/core/open-work-tracking.md +13 -2
  28. package/bundled/locales/zh-TW/core/project-context-memory.md +3 -3
  29. package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +4 -4
  30. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +1 -0
  31. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +8 -3
  32. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +5 -4
  33. package/bundled/locales/zh-TW/skills/README.md +2 -1
  34. package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md +7 -7
  35. package/bundled/locales/zh-TW/skills/open-work-assistant/SKILL.md +133 -0
  36. package/bundled/skills/.claude-plugin/plugin.json +1 -1
  37. package/bundled/skills/README.md +2 -1
  38. package/bundled/skills/dev-workflow-guide/SKILL.md +4 -4
  39. package/bundled/skills/open-work-assistant/SKILL.md +127 -0
  40. package/bundled/templates/gates/check-anti-fake-tests.mjs +183 -23
  41. package/bundled/templates/gates/check-stubs.mjs +85 -16
  42. package/package.json +2 -2
  43. package/src/commands/audit.js +4 -1
  44. package/src/commands/check.js +55 -6
  45. package/src/commands/config.js +2 -3
  46. package/src/commands/init.js +10 -3
  47. package/src/commands/update.js +239 -43
  48. package/src/i18n/messages.js +87 -0
  49. package/src/installers/hooks-installer.js +32 -5
  50. package/src/installers/skills-installer.js +45 -0
  51. package/src/reconciler/backup-locations.js +3 -2
  52. package/src/reconciler/backup-manager.js +14 -11
  53. package/src/reconciler/plan-executor.js +51 -7
  54. package/src/utils/copier.js +13 -8
  55. package/src/utils/flush-and-exit.js +37 -0
  56. package/src/utils/group-errors.js +65 -0
  57. package/src/utils/integration-generator.js +14 -5
  58. package/src/utils/skill-hash-ownership.js +33 -0
  59. package/src/utils/skill-link-rewriter.js +184 -0
  60. package/src/utils/skills-installer.js +115 -11
  61. package/src/utils/transient-fs.js +168 -14
  62. package/standards-registry.json +10 -19
  63. package/bundled/ai/standards/open-work-tracking.ai.yaml +0 -466
@@ -494,6 +494,9 @@ export async function checkCommand(options = {}) {
494
494
  { foreign: ignoredCommandRecords, elsewhere: projectCommands.ignored.length }
495
495
  );
496
496
  const commandIssues = commandIssuesOf(commandsIntegrity);
497
+ // Decision 293 (2026-11-02): installed command files that no hash covers used to be reported only.
498
+ // A report nothing acts on is how the six 6.9.0 defects stayed hidden, so `--ci` now fails on them too.
499
+ const commandUntracked = commandsIntegrity?.untracked || [];
497
500
 
498
501
  // XSPEC adopter-report Q3: neither of the two checks above (content-hash
499
502
  // integrity) says anything about an installed Skills/Commands version
@@ -573,7 +576,8 @@ export async function checkCommand(options = {}) {
573
576
  }
574
577
 
575
578
  // Reference sync check
576
- checkReferenceSync(manifest, projectPath, msg);
579
+ // Decision 293 (2026-11-02): references to files that do not exist used to be reported only; they now count.
580
+ const referenceStatus = checkReferenceSync(manifest, projectPath, msg);
577
581
 
578
582
  // Integration files check
579
583
  checkIntegrationFiles(manifest, projectPath, msg);
@@ -631,6 +635,8 @@ export async function checkCommand(options = {}) {
631
635
  fileStatus.modified.length === 0 &&
632
636
  skillIssues.length === 0 &&
633
637
  commandIssues.length === 0 &&
638
+ commandUntracked.length === 0 &&
639
+ referenceStatus.broken === 0 &&
634
640
  !testChange.blocked &&
635
641
  !testGates.blocked &&
636
642
  integrationBlockStatus.modified.length === 0 &&
@@ -1815,17 +1821,43 @@ function checkAgentsMdSync(manifest, projectPath, msg) {
1815
1821
  .map(entry => resolveStandardFilename(entry, manifest.format || 'ai'))
1816
1822
  .filter(Boolean);
1817
1823
 
1824
+ // 🔴 The `.filter(Boolean)` above is also where a manifest entry the registry cannot resolve
1825
+ // disappears. The AI-tool integration check compares the index against the manifest's raw length,
1826
+ // so it warned "declares N, manifest has N+1"; this check compared against the filtered list, found
1827
+ // N == N, and ticked green for the same file in the same run. Two checks reading one manifest, and
1828
+ // only one of them noticed the entry. (reported as dev-platform #45, uds-check-ghost-standard)
1829
+ // Not a failure of the exit code: `uds update` does not prune these (standards removed upstream
1830
+ // stay in a manifest), so a non-zero exit would turn an adopter's CI red with no command that
1831
+ // clears it. The fix is that this check never says "synced" without naming what it skipped.
1832
+ const unresolvedEntries = (manifest.standards || [])
1833
+ .filter(entry => !resolveStandardFilename(entry, manifest.format || 'ai'));
1834
+ const printUnresolved = () => {
1835
+ if (unresolvedEntries.length === 0) return;
1836
+ const shown = unresolvedEntries.length <= 10
1837
+ ? unresolvedEntries.join(', ')
1838
+ : `${unresolvedEntries.slice(0, 10).join(', ')}... (+${unresolvedEntries.length - 10})`;
1839
+ console.log(chalk.yellow(` ${(msg.agentsMdUnresolvedEntries
1840
+ || 'Manifest entries that match no installed standard ({count}), not counted above: {list}')
1841
+ .replace('{count}', unresolvedEntries.length).replace('{list}', shown)}`));
1842
+ console.log(chalk.gray(` ${msg.agentsMdUnresolvedFix
1843
+ || 'They were removed upstream or misspelled. `uds update` does not prune them: delete them from the "standards" list in .standards/manifest.json.'}`));
1844
+ };
1845
+
1818
1846
  // Same as the AI-tool integration check above: an index-mode block declares a
1819
1847
  // count instead of listing names, so the name grep below cannot apply to it.
1820
1848
  const declaredCount = parseStandardsIndexCount(content);
1821
1849
  if (declaredCount !== null) {
1822
1850
  const actual = installedStandards.length;
1823
1851
  if (declaredCount === actual) {
1824
- console.log(chalk.green(` ✓ AGENTS.md ${msg.standardsSynced || 'standards synced'} (${declaredCount})`));
1852
+ // A tick only when nothing was skipped; otherwise the same facts under a warning mark.
1853
+ const mark = unresolvedEntries.length === 0 ? chalk.green('✓') : chalk.yellow('⚠');
1854
+ const paint = unresolvedEntries.length === 0 ? chalk.green : chalk.yellow;
1855
+ console.log(` ${mark} ` + paint(`AGENTS.md ${msg.standardsSynced || 'standards synced'} (${declaredCount})`));
1825
1856
  } else {
1826
1857
  console.log(chalk.yellow(` ⚠ AGENTS.md ${msg.standardsOutOfSync || 'standards out of sync'} (${declaredCount} != ${actual})`));
1827
1858
  console.log(chalk.gray(` ${msg.runUpdateToSync || 'Run "uds update" to sync'}`));
1828
1859
  }
1860
+ printUnresolved();
1829
1861
  const idxLineCount = content.split('\n').length;
1830
1862
  if (idxLineCount > 150) {
1831
1863
  console.log(chalk.yellow(` ⚠ AGENTS.md ${msg.exceedsLineLimit || 'exceeds 150 line limit'} (${idxLineCount} lines)`));
@@ -1848,7 +1880,9 @@ function checkAgentsMdSync(manifest, projectPath, msg) {
1848
1880
  }
1849
1881
 
1850
1882
  if (missingFromAgentsMd.length === 0) {
1851
- console.log(chalk.green(` ✓ AGENTS.md ${msg.standardsSynced || 'standards synced'} (${listedCount}/${aiYamlStandards.length})`));
1883
+ const mark = unresolvedEntries.length === 0 ? chalk.green('✓') : chalk.yellow('⚠');
1884
+ const paint = unresolvedEntries.length === 0 ? chalk.green : chalk.yellow;
1885
+ console.log(` ${mark} ` + paint(`AGENTS.md ${msg.standardsSynced || 'standards synced'} (${listedCount}/${aiYamlStandards.length})`));
1852
1886
  } else {
1853
1887
  console.log(chalk.yellow(` ⚠ AGENTS.md ${msg.standardsOutOfSync || 'standards out of sync'} (${listedCount}/${aiYamlStandards.length})`));
1854
1888
  if (missingFromAgentsMd.length <= 5) {
@@ -1858,6 +1892,7 @@ function checkAgentsMdSync(manifest, projectPath, msg) {
1858
1892
  }
1859
1893
  console.log(chalk.gray(` ${msg.runUpdateToSync || 'Run "uds update" to sync'}`));
1860
1894
  }
1895
+ printUnresolved();
1861
1896
 
1862
1897
  // Check line count
1863
1898
  const lineCount = content.split('\n').length;
@@ -1872,9 +1907,13 @@ function checkAgentsMdSync(manifest, projectPath, msg) {
1872
1907
  * Check reference sync status between manifest standards and integration files
1873
1908
  */
1874
1909
  function checkReferenceSync(manifest, projectPath, msg) {
1910
+ // Returns { broken }: how many paths an integration file points at that do not exist
1911
+ // (dangling .standards/ references plus broken path mentions). Decision 293 makes them fail `--ci`;
1912
+ // orphaned references (a file that exists but the manifest does not list) stay a warning.
1913
+ const none = { broken: 0 };
1875
1914
  // Skip if no integrations
1876
1915
  if (!manifest.integrations || manifest.integrations.length === 0) {
1877
- return;
1916
+ return none;
1878
1917
  }
1879
1918
 
1880
1919
  // Pre-scan: collect results for files that have references
@@ -1902,11 +1941,12 @@ function checkReferenceSync(manifest, projectPath, msg) {
1902
1941
  }
1903
1942
 
1904
1943
  // Skip entire section if no files have references
1905
- if (results.length === 0) return;
1944
+ if (results.length === 0) return none;
1906
1945
 
1907
1946
  console.log(chalk.cyan(msg.refSyncStatus));
1908
1947
 
1909
1948
  let hasIssues = false;
1949
+ let broken = 0;
1910
1950
 
1911
1951
  for (const { integrationPath, references, brokenMentions } of results) {
1912
1952
  // Paths mentioned anywhere in the file that resolve to nothing. Reported
@@ -1915,6 +1955,7 @@ function checkReferenceSync(manifest, projectPath, msg) {
1915
1955
  // any regeneration, and followed by an AI tool that then finds nothing.
1916
1956
  if (brokenMentions?.length > 0) {
1917
1957
  hasIssues = true;
1958
+ broken += brokenMentions.length;
1918
1959
  console.log(chalk.red(` ✗ ${integrationPath}:`));
1919
1960
  console.log(chalk.red(` ${msg.brokenMentions || 'mentions paths that do not exist in this project:'}`));
1920
1961
  for (const path of brokenMentions) {
@@ -1936,6 +1977,7 @@ function checkReferenceSync(manifest, projectPath, msg) {
1936
1977
  // the manifest-level findings because it needs no interpretation.
1937
1978
  if (danglingRefs.length > 0) {
1938
1979
  hasIssues = true;
1980
+ broken += danglingRefs.length;
1939
1981
  console.log(chalk.red(` ✗ ${integrationPath}:`));
1940
1982
  console.log(chalk.red(` ${msg.danglingRefs || 'references files that do not exist:'}`));
1941
1983
  for (const ref of danglingRefs) {
@@ -1980,6 +2022,7 @@ function checkReferenceSync(manifest, projectPath, msg) {
1980
2022
  }
1981
2023
 
1982
2024
  console.log();
2025
+ return { broken };
1983
2026
  }
1984
2027
 
1985
2028
  /**
@@ -2242,7 +2285,13 @@ export function checkCommandsIntegrity(manifest, projectPath, msg, ignored = {})
2242
2285
  const ext = agentName === 'gemini-cli' ? '.toml' : '.md';
2243
2286
  for (const name of info.commands || []) {
2244
2287
  const key = `${agentName}/${name}${ext}`;
2245
- if (!trackedKeys.has(key)) status.untracked.push(key);
2288
+ if (trackedKeys.has(key)) continue;
2289
+ // `info.commands` comes from the folder's own `.manifest.json` when there is one, and that list can still
2290
+ // name a command whose file is gone. A file that is not there is not "an installed file nothing covers";
2291
+ // since decision 293 this list decides the exit code, so it must not name what is absent.
2292
+ const dir = getCommandsDirForAgent(agentName, 'project', projectPath);
2293
+ if (dir && !existsSync(join(dir, `${name}${ext}`))) continue;
2294
+ status.untracked.push(key);
2246
2295
  }
2247
2296
  }
2248
2297
  if (status.untracked.length > 0) {
@@ -51,6 +51,7 @@ import {
51
51
  import { getMarketplaceSkillsInfo } from '../utils/github.js';
52
52
  import { regenerateIntegrations } from './update.js';
53
53
  import { mergeInstalledNames, bumpManifestVersion } from '../core/manifest.js';
54
+ import { replaceSkillHashesForInstalled } from '../utils/skill-hash-ownership.js';
54
55
 
55
56
  /**
56
57
  * Get localized message with fallback (for config-specific keys)
@@ -1008,9 +1009,7 @@ export async function runProjectConfiguration(options) {
1008
1009
  }
1009
1010
  }
1010
1011
  manifest.skills.names = mergeInstalledNames(manifest.skills.names, skillResult);
1011
- if (skillResult.allFileHashes) {
1012
- manifest.skillHashes = { ...(manifest.skillHashes || {}), ...skillResult.allFileHashes };
1013
- }
1012
+ replaceSkillHashesForInstalled(manifest, skillResult);
1014
1013
  }
1015
1014
  }
1016
1015
  }
@@ -38,6 +38,7 @@ import { newRecorder, mkdirTracked, recordFile, persistRecorder, RECORD_KINDS }
38
38
  import { wireGitHooksPath, getLocalHooksPathConfig, stripLegacyHuskyShLine, ensureShebang, hookRunsUdsCheck, buildPreCommitBlock, buildNativePreCommitHook } from '../utils/git-hooks.js';
39
39
  import { migrateLegacyHuskyHook } from '../utils/legacy-hook-migration.js';
40
40
  import { installGateScripts } from '../utils/gate-scripts.js';
41
+ import { formatGroupedErrors } from '../utils/group-errors.js';
41
42
 
42
43
  /**
43
44
  * The values `--output-lang` accepts: the ids of the commit-message option files this UDS ships (the registry lists
@@ -272,8 +273,10 @@ export async function initCommand(options) {
272
273
  (msg.installFailed || 'Installation failed and was rolled back: {error}')
273
274
  .replace('{error}', err.message)
274
275
  ));
275
- for (const e of installErrors) {
276
- console.log(chalk.gray(` ${e}`));
276
+ // Board #81: one cause for many files (the folder `.standards/` cannot be made) is printed once, with how many files it
277
+ // hit; it used to be one 700-byte line per file, 50 and more times.
278
+ for (const line of formatGroupedErrors(installErrors, msg)) { // wire:init-groups-errors-by-cause
279
+ console.log(chalk.gray(line));
277
280
  }
278
281
  if (err.rolledBack === false) {
279
282
  console.log(chalk.yellow(
@@ -281,7 +284,11 @@ export async function initCommand(options) {
281
284
  .replace('{error}', err.rollbackError?.message || 'unknown')
282
285
  ));
283
286
  }
284
- process.exit(1);
287
+ // Not process.exit(1): when stdout is a pipe (CI, an AI assistant, the test harness) Node on macOS writes what
288
+ // does not fit into the pipe asynchronously, and process.exit() throws the rest away. The error list above is
289
+ // one long line per file, so a deep temp path pushed it past the 64 KB pipe and the end of the list - the
290
+ // locale pack, the line that says what failed last - never arrived. Setting exitCode lets the output drain.
291
+ process.exitCode = 1;
285
292
  return;
286
293
  }
287
294
 
@@ -1,5 +1,6 @@
1
1
  import chalk from 'chalk';
2
2
  import { createSpinner } from '../utils/spinner.js';
3
+ import { flushAndExit } from '../utils/flush-and-exit.js';
3
4
  import { select, confirm as inquirerConfirm, checkbox, Separator } from '@inquirer/prompts';
4
5
  import { execSync } from 'child_process';
5
6
  import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
@@ -31,7 +32,7 @@ import {
31
32
  getToolFromPath
32
33
  } from '../utils/reference-sync.js';
33
34
  import { checkForUpdates } from '../utils/npm-registry.js';
34
- import { pruneForeignSkillHashes } from '../utils/skill-hash-ownership.js';
35
+ import { pruneForeignSkillHashes, replaceSkillHashesForInstalled } from '../utils/skill-hash-ownership.js';
35
36
  import { pruneForeignCommandHashes } from '../utils/command-hash-ownership.js';
36
37
  import { pruneForeignSkillNames, pruneForeignCommandNames } from '../utils/installed-names-ownership.js';
37
38
  import { commandsUpdatedMessage } from '../utils/update-summary.js';
@@ -58,7 +59,7 @@ import {
58
59
  import { getMarketplaceSkillsInfo } from '../utils/github.js';
59
60
  import { printSkillNameCollisionWarning } from '../utils/skill-name-collision.js';
60
61
  import { detectAITools } from '../utils/detector.js';
61
- import { HOOK_CAPABLE_TOOLS, resolveHookTools, installMissingHooks, staleHookScripts } from '../installers/hooks-installer.js';
62
+ import { HOOK_CAPABLE_TOOLS, resolveHookTools, installMissingHooks, diffHookScripts, replaceStaleHookScripts } from '../installers/hooks-installer.js';
62
63
  import { persistRecorder, mergeRecorderInto, newRecorder } from '../core/install-records.js';
63
64
  import { installGateScripts, gateStandardInstalled, GATE_SCRIPTS } from '../utils/gate-scripts.js';
64
65
  import { migrateLegacyHuskyHook, migrateHuskyBlockWithoutCi, migrateOlderNativeHook } from '../utils/legacy-hook-migration.js';
@@ -431,16 +432,23 @@ export async function updateCommand(options) {
431
432
  console.log(chalk.bold(msg.title));
432
433
  console.log(chalk.gray('─'.repeat(50)));
433
434
 
434
- // Hook scripts are not part of what this command (or --apply, --force, --plan) reconciles; only
435
- // `--with-hooks` replaces them. Say so when one is out of date, because the symptom of an old
436
- // script is a hook that quietly does not do what the new version does (6.14.1-beta.1: the
435
+ // Hook scripts in scripts/hooks/ (decision 212甲, 2026-10-30). The forms that update the project
436
+ // (`--apply`, `--force`, plain `uds update`) replace the ones that are unmodified copies of an older UDS,
437
+ // after taking a backup, and keep the ones the adopter edited; `--plan` says what they would replace.
438
+ // The forms that are narrowed to something else (`--skills`, `--commands`, `--integrations-only`,
439
+ // `--standards-only`, `--sync-refs`, `--claude-target`) leave them alone and say so, because the symptom of an
440
+ // old script is a hook that quietly does not do what the new version does (6.14.1-beta.1: the
437
441
  // dangerous-command hook that never blocked).
438
442
  if (!options.withHooks && !options.rollback) {
439
- const stale = staleHookScripts(projectPath);
440
- if (stale.length) {
441
- console.log(chalk.yellow(` ! ${stale.length} hook script(s) in scripts/hooks/ are unmodified copies of an older UDS and are NOT updated by this command: ${stale.slice(0, 5).map((x) => x.path).join(', ')}${stale.length > 5 ? ', ...' : ''}`));
442
- console.log(chalk.gray(' Replace them with: uds update --with-hooks (add --plan first to see what changes)'));
443
- console.log();
443
+ if (!hookStepApplies(options)) {
444
+ const stale = diffHookScriptsQuietly(projectPath).stale;
445
+ if (stale.length) {
446
+ console.log(chalk.yellow(` ! ${stale.length} hook script(s) in scripts/hooks/ are unmodified copies of an older UDS and are NOT updated by this command: ${stale.slice(0, 5).map((x) => x.path).join(', ')}${stale.length > 5 ? ', ...' : ''}`));
447
+ console.log(chalk.gray(' Replace them with: uds update --apply (add --plan first to see what changes)'));
448
+ console.log();
449
+ }
450
+ } else if (options.plan) {
451
+ reportHookScriptsForPlan(projectPath);
444
452
  }
445
453
  }
446
454
 
@@ -681,7 +689,11 @@ export async function updateCommand(options) {
681
689
  writeManifest(manifest, projectPath);
682
690
  }
683
691
 
692
+ // Decision 212甲: a current version record says nothing about the scripts in scripts/hooks/. After the manifest
693
+ // write above, because the hook step reads and writes the manifest itself.
694
+ const hooksOnLatest = hookStepApplies(options) ? runHookScriptStep(projectPath) : { failed: false };
684
695
  console.log();
696
+ if (hooksOnLatest.failed) process.exitCode = 1;
685
697
  return;
686
698
  }
687
699
 
@@ -728,6 +740,14 @@ export async function updateCommand(options) {
728
740
  console.log(chalk.green(` + .standards/${ns.name}`));
729
741
  }
730
742
  }
743
+ // Part of what the confirmation below agrees to (decision 212甲).
744
+ if (hookStepApplies(options)) {
745
+ const hookStale = diffHookScriptsQuietly(projectPath).stale;
746
+ if (hookStale.length) {
747
+ console.log();
748
+ console.log(chalk.gray(` scripts/hooks/ - ${hookStale.length} unmodified copy(ies) of an older UDS will be replaced (copied to .uds-backups/ first): ${fmtHookList(hookStale.map((x) => x.path))}`));
749
+ }
750
+ }
731
751
  console.log();
732
752
 
733
753
  // Confirm
@@ -1360,8 +1380,7 @@ export async function updateCommand(options) {
1360
1380
 
1361
1381
  // Update skill hashes for integrity tracking
1362
1382
  if (skillResult.allFileHashes) {
1363
- if (!manifest.skillHashes) manifest.skillHashes = {};
1364
- Object.assign(manifest.skillHashes, skillResult.allFileHashes);
1383
+ replaceSkillHashesForInstalled(manifest, skillResult);
1365
1384
  }
1366
1385
 
1367
1386
  if (skillResult.totalErrors === 0) {
@@ -1398,8 +1417,7 @@ export async function updateCommand(options) {
1398
1417
 
1399
1418
  // Update skill hashes for integrity tracking
1400
1419
  if (updateResult.allFileHashes) {
1401
- if (!manifest.skillHashes) manifest.skillHashes = {};
1402
- Object.assign(manifest.skillHashes, updateResult.allFileHashes);
1420
+ replaceSkillHashesForInstalled(manifest, updateResult);
1403
1421
  }
1404
1422
 
1405
1423
  if (updateResult.totalErrors === 0) {
@@ -1529,8 +1547,7 @@ export async function updateCommand(options) {
1529
1547
  manifest.skills.installations = deduplicateInstallations([...(manifest.skills.installations || []), ...missingSkills]);
1530
1548
  manifest.skills.names = mergeInstalledNames(manifest.skills.names, result);
1531
1549
  if (result.allFileHashes) {
1532
- if (!manifest.skillHashes) manifest.skillHashes = {};
1533
- Object.assign(manifest.skillHashes, result.allFileHashes);
1550
+ replaceSkillHashesForInstalled(manifest, result);
1534
1551
  }
1535
1552
  if (result.totalErrors === 0) {
1536
1553
  spinner.succeed((msg.newSkillsInstalled || 'Installed Skills for {count} AI tools').replace('{count}', missingSkills.length));
@@ -1553,8 +1570,7 @@ export async function updateCommand(options) {
1553
1570
  manifest.skills.location = uniqueLevels.length === 1 ? uniqueLevels[0] : (uniqueLevels.length > 1 ? 'multiple' : undefined);
1554
1571
  }
1555
1572
  if (result.allFileHashes) {
1556
- if (!manifest.skillHashes) manifest.skillHashes = {};
1557
- Object.assign(manifest.skillHashes, result.allFileHashes);
1573
+ replaceSkillHashesForInstalled(manifest, result);
1558
1574
  }
1559
1575
  if (result.totalErrors === 0) {
1560
1576
  spinner.succeed((msg.skillsUpdated || 'Updated Skills for {count} AI tools').replace('{count}', outdatedSkills.length));
@@ -1691,6 +1707,13 @@ export async function updateCommand(options) {
1691
1707
  }
1692
1708
  }
1693
1709
 
1710
+ // Decision 212甲: replace the unmodified old hook scripts (backup first). After every manifest write above.
1711
+ let hookStepFailed = false;
1712
+ if (hookStepApplies(options)) {
1713
+ console.log();
1714
+ hookStepFailed = runHookScriptStep(projectPath).failed;
1715
+ }
1716
+
1694
1717
  console.log();
1695
1718
 
1696
1719
  // 錯誤訊息單一出口閘門:問過才寫,而且從不覆寫。
@@ -1701,7 +1724,9 @@ export async function updateCommand(options) {
1701
1724
 
1702
1725
  // Exit explicitly to prevent hanging.
1703
1726
  // T11: a partial update exits non-zero so CI / scripts can detect the failure.
1704
- process.exit(updateIncomplete ? 1 : 0);
1727
+ // Board #81: the list of failed files above grows with the project (144 KB measured); process.exit() alone cut it
1728
+ // at one pipe's worth (65,536 bytes) on macOS, so wait for the output to be taken before ending.
1729
+ await flushAndExit(updateIncomplete || hookStepFailed ? 1 : 0); // wire:update-flushes-before-exit
1705
1730
  }
1706
1731
 
1707
1732
  /**
@@ -2048,15 +2073,24 @@ export async function updateHooksOnly(projectPath, manifest, options = {}) {
2048
2073
  console.log(chalk.gray(` ${tool}: ${resolved.sources[tool].join(', ')}`));
2049
2074
  }
2050
2075
 
2051
- const { results, scripts, artifacts } = installMissingHooks(projectPath, resolved.tools, {
2076
+ const install = () => installMissingHooks(projectPath, resolved.tools, {
2052
2077
  plan: !!options.plan,
2053
2078
  overwriteScripts: !!options.force,
2054
2079
  });
2080
+ // A real run takes a rollback point first: the unmodified old scripts that are about to be replaced, and with
2081
+ // `--force` the edited ones that are about to be overwritten, are copied to `.uds-backups/` (decision 212甲).
2082
+ const guarded = options.plan
2083
+ ? { ok: true, value: install(), backupId: null }
2084
+ : withHookScriptBackup(projectPath, { overwrite: !!options.force, watchNew: true }, install);
2085
+ if (!guarded.ok) return; // nothing changed (no backup) or the write failed and was undone; already explained
2086
+ const { results, scripts, artifacts } = guarded.value;
2055
2087
 
2056
2088
  // Record what was just written (hook scripts, and folders UDS had to create) in
2057
2089
  // the manifest, so `uds uninstall` can remove exactly that. Never on --plan: a
2058
2090
  // plan writes nothing, and the recorder is empty then anyway.
2059
2091
  if (!options.plan) persistRecorder(projectPath, artifacts);
2092
+ // After the manifest write, so the backup records the manifest this step left behind.
2093
+ if (guarded.backupId) finalizeBackup(projectPath, guarded.backupId);
2060
2094
 
2061
2095
  let failed = false;
2062
2096
  for (const r of results) {
@@ -2068,26 +2102,14 @@ export async function updateHooksOnly(projectPath, manifest, options = {}) {
2068
2102
  }
2069
2103
  // Scripts are judged apart from the hook config: a config that is already there says nothing about
2070
2104
  // whether the script beside it is current (6.14.1-beta.1 shipped a security fix to exactly such a script).
2071
- const fmt = (list) => `${list.slice(0, 5).join(', ')}${list.length > 5 ? ', ...' : ''}`;
2072
- // A plan reports what is measured; a real run reports only what the installer says it WROTE
2073
- // (`replaced`), never what it measured — so a refresh that did nothing cannot print "replaced".
2074
- const sinceOf = new Map((scripts.stale ?? []).map((x) => [x.path, x.since]));
2075
- const stale = (options.plan ? (scripts.stale ?? []).map((x) => x.path) : (scripts.replaced ?? []));
2076
- if (stale.length) {
2077
- const named = fmt(stale.map((p) => `${p} (unmodified copy from UDS ${sinceOf.get(p)})`));
2078
- if (options.plan) console.log(chalk.cyan(` + would replace ${stale.length} out-of-date hook script(s) in scripts/hooks/: ${named}`));
2079
- else console.log(chalk.green(` ✓ replaced ${stale.length} out-of-date hook script(s) in scripts/hooks/: ${named}`));
2080
- }
2081
- const overwritten = options.plan ? (options.force ? scripts.kept : []) : (scripts.overwritten ?? []);
2082
- if (overwritten.length) {
2083
- if (options.plan) console.log(chalk.cyan(` + --force would overwrite ${overwritten.length} edited hook script(s): ${fmt(overwritten)}`));
2084
- else console.log(chalk.yellow(` ! --force: overwrote ${overwritten.length} edited hook script(s) with the shipped version: ${fmt(overwritten)}`));
2085
- }
2086
- const kept = options.plan && options.force ? [] : scripts.kept;
2087
- if (kept.length) {
2088
- console.log(chalk.yellow(` ! ${kept.length} hook script(s) in scripts/hooks/ differ from this UDS version and ${options.plan ? 'would be' : 'were'} kept: ${fmt(kept)}`));
2089
- console.log(chalk.gray(' They match no copy UDS ever shipped, so they look edited (or are not UDS\'s). An edited script does not receive fixes made to the shipped one.'));
2090
- console.log(chalk.gray(' Add --force to overwrite them with the shipped versions.'));
2105
+ const { stale, overwritten } = printHookScriptReport(scripts, {
2106
+ plan: !!options.plan,
2107
+ force: !!options.force,
2108
+ forceCommand: 'uds update --with-hooks --force'
2109
+ });
2110
+ if (guarded.backupId) {
2111
+ printBackupLocation(guarded.backupId);
2112
+ printBackupCleanup(guarded.cleanup);
2091
2113
  }
2092
2114
  if (results.some((r) => r.tool === 'antigravity' && r.outcome === 'installed')) {
2093
2115
  console.log(chalk.yellow(' ⚠ Verified against a real agy session for a single turn without tool calls in `agy -p` mode only; multi-turn, tool-call turns and interactive mode are not yet verified.'));
@@ -3054,8 +3076,7 @@ async function updateSkillsOnly(projectPath, manifest, options, { chained = fals
3054
3076
 
3055
3077
  // Update skill hashes for integrity tracking
3056
3078
  if (result.allFileHashes) {
3057
- if (!manifest.skillHashes) manifest.skillHashes = {};
3058
- Object.assign(manifest.skillHashes, result.allFileHashes);
3079
+ replaceSkillHashesForInstalled(manifest, result);
3059
3080
  }
3060
3081
  // XSPEC-454 R2: and forget the records that were never UDS's (the manifest this merges into
3061
3082
  // may come from an installer that hashed the whole skills folder).
@@ -3652,6 +3673,159 @@ function finishStepBackup(projectPath, backup) {
3652
3673
  printBackupCleanup(backup.cleanup);
3653
3674
  }
3654
3675
 
3676
+ // ─── Hook scripts in scripts/hooks/ (decision 212甲) ─────────────────
3677
+
3678
+ /**
3679
+ * Does this invocation replace out-of-date hook scripts? Same gate as the pre-commit migration: a run narrowed to
3680
+ * something else stays narrowed, and `--with-hooks` has its own path (updateHooksOnly).
3681
+ */
3682
+ function hookStepApplies(options) {
3683
+ return !options.rollback && !options.withHooks && !options.skills && !options.commands
3684
+ && !options.standardsOnly && !options.integrationsOnly && !options.syncRefs && !options.claudeTarget;
3685
+ }
3686
+
3687
+ /** The measured state of scripts/hooks/, or an empty one: a notice about scripts is never why `uds update` fails. */
3688
+ function diffHookScriptsQuietly(projectPath) {
3689
+ try {
3690
+ return diffHookScripts(projectPath);
3691
+ } catch {
3692
+ return { added: 0, addedPaths: [], identical: 0, stale: [], kept: [] };
3693
+ }
3694
+ }
3695
+
3696
+ const hookRel = (p) => `scripts/hooks/${p}`;
3697
+ const fmtHookList = (list) => `${list.slice(0, 5).join(', ')}${list.length > 5 ? ', ...' : ''}`;
3698
+
3699
+ /**
3700
+ * Print what happened (or, with `plan`, what would happen) to the hook scripts. One set of lines for every
3701
+ * command that touches them. Returns the three lists it printed.
3702
+ *
3703
+ * @param {{ stale?: Array<{path:string, since:string}>, kept: string[], replaced?: string[], overwritten?: string[] }} scripts
3704
+ * @param {{ plan?: boolean, force?: boolean, forceCommand: string }} ctx
3705
+ */
3706
+ function printHookScriptReport(scripts, { plan = false, force = false, forceCommand }) {
3707
+ // A plan reports what is measured; a real run reports only what the installer says it WROTE
3708
+ // (`replaced`), never what it measured — so a refresh that did nothing cannot print "replaced".
3709
+ const sinceOf = new Map((scripts.stale ?? []).map((x) => [x.path, x.since]));
3710
+ const stale = plan ? (scripts.stale ?? []).map((x) => x.path) : (scripts.replaced ?? []);
3711
+ if (stale.length) {
3712
+ const named = fmtHookList(stale.map((p) => `${p} (unmodified copy from UDS ${sinceOf.get(p)})`));
3713
+ if (plan) console.log(chalk.cyan(` + would replace ${stale.length} out-of-date hook script(s) in scripts/hooks/: ${named}`));
3714
+ else console.log(chalk.green(` ✓ replaced ${stale.length} out-of-date hook script(s) in scripts/hooks/: ${named}`));
3715
+ }
3716
+ const overwritten = plan ? (force ? scripts.kept : []) : (scripts.overwritten ?? []);
3717
+ if (overwritten.length) {
3718
+ if (plan) console.log(chalk.cyan(` + --force would overwrite ${overwritten.length} edited hook script(s): ${fmtHookList(overwritten)}`));
3719
+ else console.log(chalk.yellow(` ! --force: overwrote ${overwritten.length} edited hook script(s) with the shipped version: ${fmtHookList(overwritten)}`));
3720
+ }
3721
+ const kept = plan && force ? [] : scripts.kept;
3722
+ if (kept.length) {
3723
+ console.log(chalk.yellow(` ! ${kept.length} hook script(s) in scripts/hooks/ differ from this UDS version and ${plan ? 'would be' : 'were'} kept: ${fmtHookList(kept)}`));
3724
+ console.log(chalk.gray(' They match no copy UDS ever shipped, so they look edited (or are not UDS\'s). An edited script does not receive fixes made to the shipped one.'));
3725
+ console.log(chalk.gray(` To overwrite them with the shipped versions (a backup is taken first): ${forceCommand}`));
3726
+ }
3727
+ return { stale, overwritten, kept };
3728
+ }
3729
+
3730
+ /** `--plan`: say which hook scripts `uds update --apply` (and plain `uds update`) would replace. Writes nothing. */
3731
+ function reportHookScriptsForPlan(projectPath) {
3732
+ const scripts = diffHookScriptsQuietly(projectPath);
3733
+ if (!scripts.stale.length && !scripts.kept.length) return;
3734
+ printHookScriptReport(scripts, { plan: true, forceCommand: 'uds update --with-hooks --force' });
3735
+ console.log();
3736
+ }
3737
+
3738
+ /**
3739
+ * Rewrite hook scripts with a rollback point (decision 212甲).
3740
+ *
3741
+ * The scripts about to be overwritten - the unmodified old copies and, when `overwrite`, the edited ones - are
3742
+ * copied into a backup first, in the same `.uds-backups/` folder and format as every other step, so
3743
+ * `uds update --rollback` puts them back. `write` then does the writing; if it throws, the backup is applied
3744
+ * on the spot and nothing is left half-replaced.
3745
+ *
3746
+ * @param {string} projectPath
3747
+ * @param {{ overwrite?: boolean, watchNew?: boolean }} opts
3748
+ * overwrite: the edited scripts are overwritten too (`--with-hooks --force`)
3749
+ * watchNew: also watch the scripts that do not exist yet, so a rollback removes what the step created
3750
+ * @param {() => any} write
3751
+ * @returns {{ ok: boolean, value?: any, backupId: string|null, cleanup?: object|null }}
3752
+ * `ok: false`: nothing was changed (no backup could be taken) or the write failed and was undone; the
3753
+ * explanation is already printed and the exit code set.
3754
+ */
3755
+ function withHookScriptBackup(projectPath, { overwrite = false, watchNew = false } = {}, write) {
3756
+ const diff = diffHookScripts(projectPath);
3757
+ const targets = [...diff.stale.map((x) => hookRel(x.path)), ...(overwrite ? diff.kept.map(hookRel) : [])];
3758
+ if (targets.length === 0) return { ok: true, value: write(), backupId: null };
3759
+
3760
+ const backup = createStepBackup(projectPath, {
3761
+ label: 'hooks',
3762
+ mustBackUp: targets,
3763
+ paths: watchNew ? diff.addedPaths.map(hookRel) : []
3764
+ });
3765
+ const missing = targets.filter((t) => !backup.backedUp.includes(t));
3766
+ if (backup.errors.length > 0 || missing.length > 0) {
3767
+ console.log(chalk.red('Could not take a backup before replacing hook scripts; nothing was changed.'));
3768
+ for (const err of backup.errors) console.log(chalk.red(` ${err}`));
3769
+ for (const m of missing) console.log(chalk.red(` Not backed up: ${m}`));
3770
+ console.log();
3771
+ process.exitCode = 1;
3772
+ return { ok: false, backupId: backup.backupId };
3773
+ }
3774
+ const cleanup = cleanupBackupsQuietly(projectPath);
3775
+
3776
+ try {
3777
+ return { ok: true, value: write(), backupId: backup.backupId, cleanup };
3778
+ } catch (err) {
3779
+ // The write failed part-way. Finalize first so the backup knows what the step created, then put everything back.
3780
+ finalizeBackup(projectPath, backup.backupId);
3781
+ const undo = rollbackLast(projectPath, backup.backupId);
3782
+ console.log(chalk.red(` ✗ Replacing hook scripts failed: ${err.message}`));
3783
+ if (undo.success) {
3784
+ console.log(chalk.yellow(` The hook scripts were restored from the backup (${backup.backupId}); none was left half-replaced.`));
3785
+ } else {
3786
+ console.log(chalk.red(` Restoring them from the backup ALSO failed: ${undo.errors.join('; ')}`));
3787
+ console.log(chalk.red(` Copy the files back by hand from ${backup.backupId}/scripts/hooks/.`));
3788
+ }
3789
+ console.log();
3790
+ process.exitCode = 1;
3791
+ return { ok: false, backupId: backup.backupId };
3792
+ }
3793
+ }
3794
+
3795
+ /**
3796
+ * The hook-script step of `uds update --apply`, `--force` and plain `uds update`: replace the unmodified old
3797
+ * copies (backup first), keep the edited ones and say so. Never installs a hook config or a script that is not
3798
+ * there yet - that stays `--with-hooks`.
3799
+ *
3800
+ * Never throws: a hook-script problem is reported and sets the exit code, it does not abort the rest of the update.
3801
+ *
3802
+ * @returns {{ replaced: string[], failed: boolean }}
3803
+ */
3804
+ function runHookScriptStep(projectPath) {
3805
+ try {
3806
+ const before = diffHookScripts(projectPath);
3807
+ if (before.stale.length === 0 && before.kept.length === 0) return { replaced: [], failed: false };
3808
+
3809
+ const guarded = withHookScriptBackup(projectPath, {}, () => replaceStaleHookScripts(projectPath));
3810
+ if (!guarded.ok) return { replaced: [], failed: true };
3811
+ const { scripts, artifacts } = guarded.value;
3812
+ // Record what was written in the manifest first, then finalize: the backup notes the manifest it left behind.
3813
+ persistRecorder(projectPath, artifacts);
3814
+ if (guarded.backupId) finalizeBackup(projectPath, guarded.backupId);
3815
+ const printed = printHookScriptReport(scripts, { forceCommand: 'uds update --with-hooks --force' });
3816
+ if (guarded.backupId) {
3817
+ printBackupLocation(guarded.backupId);
3818
+ printBackupCleanup(guarded.cleanup);
3819
+ }
3820
+ console.log();
3821
+ return { replaced: printed.stale, failed: false };
3822
+ } catch (err) {
3823
+ console.log(chalk.yellow(` ! Could not check the hook scripts in scripts/hooks/: ${err.message}`));
3824
+ console.log();
3825
+ return { replaced: [], failed: false };
3826
+ }
3827
+ }
3828
+
3655
3829
  /**
3656
3830
  * Say where the backup is, how to undo, and what to exclude (XSPEC-456 R7). All backups share one folder,
3657
3831
  * `.uds-backups/`, so a tool that does not read .gitignore (an indexer, IDE search, grep) can be told to
@@ -3845,6 +4019,9 @@ async function handlePlan(projectPath, options, manifest, addStandards = []) {
3845
4019
  * @param {{ force: boolean }} mode
3846
4020
  */
3847
4021
  async function handleReconcile(projectPath, options, { force, addStandards = [] }) {
4022
+ // Decision 212甲: the hook scripts in scripts/hooks/ are part of what --apply brings up to date (a run narrowed
4023
+ // to --skills/--commands is not: see hookStepApplies).
4024
+ const replacesHooks = hookStepApplies(options);
3848
4025
  console.log(chalk.cyan(
3849
4026
  force
3850
4027
  ? 'Running declarative state reconciliation (force mode)...'
@@ -3875,7 +4052,12 @@ async function handleReconcile(projectPath, options, { force, addStandards = []
3875
4052
  droppedNames = before - ((current.skills?.names?.length || 0) + (current.commands?.names?.length || 0)); // wire:up-to-date-prunes-names
3876
4053
  }
3877
4054
  if (current && ((pruneForeignSkillHashes(current).length + pruneForeignCommandHashes(current).length) > 0 || aligned || droppedNames > 0)) writeManifest(current, projectPath);
3878
- console.log(chalk.green('Everything is up to date. No changes needed.'));
4055
+ // The reconciler has nothing to do, but a project whose version record is current can still be running a
4056
+ // hook script from an older UDS (6.14.1 `--apply` recorded the new version and left the old script).
4057
+ const hookStep = replacesHooks ? runHookScriptStep(projectPath) : { replaced: [] };
4058
+ console.log(chalk.green(hookStep.replaced.length > 0
4059
+ ? 'Standards, skills and integrations are up to date; only hook scripts needed changes.'
4060
+ : 'Everything is up to date. No changes needed.'));
3879
4061
  if (droppedNames > 0) console.log(chalk.gray(` ${t().commands.update.droppedForeignNames.replace('{count}', droppedNames)}`));
3880
4062
  // XSPEC-458 R2: "up to date" is about the files UDS manages; say what UDS ships that is not managed here.
3881
4063
  printAvailableStandardsSection(planResult.manifest, { phase: 'apply' });
@@ -3885,6 +4067,14 @@ async function handleReconcile(projectPath, options, { force, addStandards = []
3885
4067
 
3886
4068
  console.log(formatPlan(planResult.plan));
3887
4069
  console.log();
4070
+ // Not in the reconciler's plan, but part of what the confirmation below agrees to.
4071
+ if (replacesHooks) {
4072
+ const hookStale = diffHookScriptsQuietly(projectPath).stale;
4073
+ if (hookStale.length) {
4074
+ console.log(chalk.cyan(` + ${hookStale.length} hook script(s) in scripts/hooks/ will be replaced (unmodified copies of an older UDS; copied to .uds-backups/ first): ${fmtHookList(hookStale.map((x) => x.path))}`));
4075
+ console.log();
4076
+ }
4077
+ }
3888
4078
 
3889
4079
  // Confirm unless --yes
3890
4080
  {
@@ -3930,6 +4120,12 @@ async function handleReconcile(projectPath, options, { force, addStandards = []
3930
4120
  }
3931
4121
  }
3932
4122
 
4123
+ // Hook scripts are independent of the plan above: replaced (backup first) whether or not every action succeeded.
4124
+ if (replacesHooks) {
4125
+ console.log();
4126
+ runHookScriptStep(projectPath);
4127
+ }
4128
+
3933
4129
  if (!result.success) {
3934
4130
  // XSPEC-482 R10: say what a partly failed run left behind and the way to finish it.
3935
4131
  console.log();