universal-dev-standards 6.14.0-beta.11 → 6.14.0-beta.13

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 (46) hide show
  1. package/bin/uds.js +8 -1
  2. package/bundled/ai/standards/secret-management-standards.ai.yaml +12 -1
  3. package/bundled/core/secret-management-standards.md +13 -1
  4. package/bundled/hooks/validate-commit-msg.mjs +52 -9
  5. package/bundled/locales/zh-CN/CHANGELOG.md +3 -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/docs/CHEATSHEET.md +1 -1
  9. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +4 -3
  10. package/bundled/locales/zh-TW/CHANGELOG.md +3 -3
  11. package/bundled/locales/zh-TW/README.md +1 -1
  12. package/bundled/locales/zh-TW/SECURITY.md +1 -1
  13. package/bundled/locales/zh-TW/core/secret-management-standards.md +12 -4
  14. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +1 -1
  15. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +4 -3
  16. package/package.json +1 -1
  17. package/src/commands/audit.js +28 -1
  18. package/src/commands/check.js +72 -3
  19. package/src/commands/compile.js +37 -4
  20. package/src/commands/config.js +28 -19
  21. package/src/commands/init.js +59 -28
  22. package/src/commands/release-messages.js +228 -0
  23. package/src/commands/release.js +72 -72
  24. package/src/commands/spec.js +4 -2
  25. package/src/commands/update.js +114 -12
  26. package/src/compilers/claude-code-compiler.js +9 -1
  27. package/src/i18n/messages.js +96 -0
  28. package/src/installers/hooks-installer.js +1 -1
  29. package/src/mcp/server.js +9 -3
  30. package/src/prompts/init.js +17 -17
  31. package/src/reconciler/plan-executor.js +63 -5
  32. package/src/reconciler/recorded-versions.js +49 -0
  33. package/src/uninstallers/hook-uninstaller.js +9 -1
  34. package/src/uninstallers/skills-uninstaller.js +10 -3
  35. package/src/utils/available-standards-report.js +25 -4
  36. package/src/utils/available-standards.js +13 -3
  37. package/src/utils/build-manifest.js +1 -1
  38. package/src/utils/commit-message-judge.js +38 -9
  39. package/src/utils/friction-detector.js +23 -11
  40. package/src/utils/git-hooks.js +106 -4
  41. package/src/utils/integration-generator.js +75 -49
  42. package/src/utils/legacy-hook-migration.js +121 -2
  43. package/src/utils/sdd-header.js +11 -0
  44. package/src/utils/spinner.js +14 -4
  45. package/src/utils/standard-validator.js +3 -2
  46. package/standards-registry.json +10 -8
@@ -29,6 +29,10 @@ export const messages = {
29
29
  categoryLine: '{category} ({count})',
30
30
  installHint: 'Install one: uds update --apply --add-standard <id> (repeat the flag for several; add --plan to preview first)',
31
31
  othersLine: 'Not listed above: {count} more standard(s) in categories `uds init` never installs ({breakdown}). Any of them can still be installed by id with --add-standard.',
32
+ recommendedTitle: 'Recommended core standards, not installed ({count})',
33
+ recommendedApply: '{count} recommended core standard(s) are not installed ({ids}); see them with uds update --plan.',
34
+ checkRecommended: '{count} recommended core standard(s) not installed ({ids}) — run `uds update --plan` for the install commands',
35
+ frictionRecommended: '{count} recommended core standard(s) not installed',
32
36
  applySummary: '{count} standard(s) UDS ships are not installed in this project (no file was changed for them).',
33
37
  applyHint: 'See them: uds update --plan Install one: uds update --apply --add-standard <id>',
34
38
  checkLine: '{count} upstream standard(s) not installed — run `uds update --plan` to see them',
@@ -256,6 +260,26 @@ export const messages = {
256
260
  },
257
261
 
258
262
  // Release Mode
263
+ // Prompts of the optional uds.project.yaml step of `uds init` (XSPEC-482 R13: they were English in every language).
264
+ projectContract: {
265
+ confirmCreate: 'Create uds.project.yaml (project command contract)?',
266
+ title: '📋 Project Command Contract (uds.project.yaml)',
267
+ intro1: 'Tell UDS how to run standard commands in this project (language-agnostic).',
268
+ intro2: 'Press Enter to accept a suggestion, or type your own. Leave blank to skip.',
269
+ detected: 'Detected suggestions:',
270
+ alreadyExists: 'uds.project.yaml already exists.',
271
+ keptSections: 'These sections are kept exactly as they are: {sections}.',
272
+ noOtherSections: 'It has no other sections.',
273
+ updateQuestion: 'Update the commands (test, lint, build, security) in the existing uds.project.yaml? {kept}',
274
+ replaceQuestion: 'The existing uds.project.yaml cannot be read as YAML, so none of its content can be kept. Replace the whole file?',
275
+ skippedKeeping: 'Skipped — keeping existing uds.project.yaml',
276
+ commandOptional: '{intent} command (optional):',
277
+ commandDefault: '{intent} command (default: {value}):',
278
+ noneEntered: 'No commands entered — uds.project.yaml not created.',
279
+ updated: '✔ uds.project.yaml updated (other sections kept as they were)',
280
+ created: '✔ uds.project.yaml created',
281
+ path: 'Path: {path}'
282
+ },
259
283
  releaseMode: {
260
284
  title: 'Release Mode:',
261
285
  description: 'Choose release mode, affects how versions are published',
@@ -1142,6 +1166,14 @@ export const messages = {
1142
1166
  hookWouldMigrate: '+ .husky/pre-commit: would replace the line an older UDS wrote (it asks npm to resolve the bare name "uds", which is not this project) with one that runs only the installed UDS CLI.',
1143
1167
  hookLegacyKept: '⚠ .husky/pre-commit line {line} ("{text}") asks npm to resolve the bare name "uds", which on the npm registry is an unrelated package. UDS did not write this exact line, so it was left alone. Change it to "universal-dev-standards check" — it needs the UDS CLI installed in this project or on PATH.',
1144
1168
  hookMigrateFailed: '⚠ Could not rewrite .husky/pre-commit: {error}. The line that asks npm for the bare name "uds" is still there — change it to "universal-dev-standards check".',
1169
+ hookNativeMigrated: '✓ .git/hooks/pre-commit: replaced the hook an older UDS wrote ({from}) with the current one. The old one ran the check with its errors thrown away and let every commit through; the new one stops a commit when `check --ci` reports an issue.',
1170
+ hookNativeWouldMigrate: '+ .git/hooks/pre-commit: would replace the hook an older UDS wrote ({from}) with the current one. The old one ran the check with its errors thrown away and let every commit through; the new one stops a commit when `check --ci` reports an issue.',
1171
+ hookNativeKept: '⚠ .git/hooks/pre-commit line {line} ("{text}") runs the UDS check and lets the commit through whatever it finds. The file is not exactly what UDS wrote, so it was left alone. Change that line to "universal-dev-standards check --ci" — it needs the UDS CLI installed in this project or on PATH.',
1172
+ hookHuskyCiMigrated: '✓ .husky/pre-commit: the UDS block now runs `check --ci`, so the hook stops a commit when the check finds an issue. (The block an earlier beta wrote ran `check` alone, which exits 0 even when a standard file was edited.)',
1173
+ hookHuskyCiWouldMigrate: '+ .husky/pre-commit: would change the UDS block to run `check --ci`, so the hook stops a commit when the check finds an issue. (The block an earlier beta wrote ran `check` alone, which exits 0 even when a standard file was edited.)',
1174
+ hookNativeFromLegacy: 'UDS 5.x to 6.13.1: `uds check 2>/dev/null || true`',
1175
+ hookNativeFromWithoutCi: 'UDS 6.14.0 betas: `check` without `--ci`',
1176
+ hookNativeFailed: '⚠ Could not rewrite .git/hooks/pre-commit: {error}. It still lets every commit through — replace its UDS check line with "universal-dev-standards check --ci".',
1145
1177
  newerVersion: '(You have a newer version than the registry: {version})',
1146
1178
  updateAvailable: 'Update available: {current} → {latest}',
1147
1179
  // Files
@@ -1402,6 +1434,10 @@ export const messages = {
1402
1434
  categoryLine: '{category}({count})',
1403
1435
  installHint: '要裝其中一個:uds update --apply --add-standard <id>(可重複旗標裝多個;先加 --plan 預覽)',
1404
1436
  othersLine: '上面沒列出的另有 {count} 個標準,屬於 `uds init` 從不安裝的類別({breakdown});它們仍可用 --add-standard 指名安裝。',
1437
+ recommendedTitle: '建議安裝的 core 標準,尚未安裝({count} 個)',
1438
+ recommendedApply: '有 {count} 個建議安裝的 core 標準沒裝({ids});用 uds update --plan 查看。',
1439
+ checkRecommended: '有 {count} 個建議安裝的 core 標準未安裝({ids})— 執行 `uds update --plan` 看安裝指令',
1440
+ frictionRecommended: '{count} 個建議安裝的 core 標準未安裝',
1405
1441
  applySummary: '上游有 {count} 個標準沒裝在這個專案(沒有為它們改動任何檔案)。',
1406
1442
  applyHint: '查看:uds update --plan 安裝其中一個:uds update --apply --add-standard <id>',
1407
1443
  checkLine: '上游有 {count} 個標準未安裝 — 執行 `uds update --plan` 查看',
@@ -1629,6 +1665,26 @@ export const messages = {
1629
1665
  },
1630
1666
 
1631
1667
  // Release Mode
1668
+ // `uds init` 選填 uds.project.yaml 步驟的提問(XSPEC-482 R13:原本每種語言都是英文)。
1669
+ projectContract: {
1670
+ confirmCreate: '要建立 uds.project.yaml(專案指令契約)嗎?',
1671
+ title: '📋 專案指令契約(uds.project.yaml)',
1672
+ intro1: '告訴 UDS 這個專案如何執行標準指令(與程式語言無關)。',
1673
+ intro2: '按 Enter 接受建議值,或自行輸入。留空代表略過。',
1674
+ detected: '偵測到的建議值:',
1675
+ alreadyExists: 'uds.project.yaml 已存在。',
1676
+ keptSections: '這些區段會原封不動保留:{sections}。',
1677
+ noOtherSections: '它沒有其他區段。',
1678
+ updateQuestion: '要更新現有 uds.project.yaml 裡的指令(test、lint、build、security)嗎?{kept}',
1679
+ replaceQuestion: '現有的 uds.project.yaml 無法當成 YAML 讀取,所以其中內容都無法保留。要整份取代嗎?',
1680
+ skippedKeeping: '已略過——保留現有的 uds.project.yaml',
1681
+ commandOptional: '{intent} 指令(選填):',
1682
+ commandDefault: '{intent} 指令(預設:{value}):',
1683
+ noneEntered: '沒有輸入任何指令——未建立 uds.project.yaml。',
1684
+ updated: '✔ uds.project.yaml 已更新(其他區段維持原樣)',
1685
+ created: '✔ 已建立 uds.project.yaml',
1686
+ path: '路徑:{path}'
1687
+ },
1632
1688
  releaseMode: {
1633
1689
  title: '發布模式:',
1634
1690
  description: '選擇發布模式,影響版本如何發布',
@@ -2510,6 +2566,14 @@ export const messages = {
2510
2566
  hookWouldMigrate: '+ .husky/pre-commit:將把舊版 UDS 寫入的那一行(它會請 npm 解析裸名稱 uds,而那不是本專案)換成只執行已安裝 UDS CLI 的寫法。',
2511
2567
  hookLegacyKept: '⚠ .husky/pre-commit 第 {line} 行(「{text}」)會請 npm 解析裸名稱 uds,而它在 npm registry 上是不相干的套件。這一行不是 UDS 寫入的原樣,所以沒有動它。請自行改成 universal-dev-standards check——需要在本專案或 PATH 上已安裝 UDS CLI。',
2512
2568
  hookMigrateFailed: '⚠ 無法改寫 .husky/pre-commit:{error}。請 npm 解析裸名稱 uds 的那一行仍在,請自行改成 universal-dev-standards check。',
2569
+ hookNativeMigrated: '✓ .git/hooks/pre-commit:已把舊版 UDS 寫入的掛鉤({from})換成現行版本。舊的會把檢查的錯誤丟掉、讓每個 commit 都通過;新的會在 `check --ci` 回報問題時擋下 commit。',
2570
+ hookNativeWouldMigrate: '+ .git/hooks/pre-commit:將把舊版 UDS 寫入的掛鉤({from})換成現行版本。舊的會把檢查的錯誤丟掉、讓每個 commit 都通過;新的會在 `check --ci` 回報問題時擋下 commit。',
2571
+ hookNativeKept: '⚠ .git/hooks/pre-commit 第 {line} 行(「{text}」)會執行 UDS 檢查,但不論查到什麼都讓 commit 通過。這個檔案不是 UDS 寫入的原樣,所以沒有動它。請自行把那一行改成 universal-dev-standards check --ci——需要在本專案或 PATH 上已安裝 UDS CLI。',
2572
+ hookHuskyCiMigrated: '✓ .husky/pre-commit:UDS 區塊現在執行 `check --ci`,檢查發現問題時掛鉤會擋下 commit。(較早的 beta 寫入的區塊只跑 `check`,標準檔被改了也回 0。)',
2573
+ hookHuskyCiWouldMigrate: '+ .husky/pre-commit:將把 UDS 區塊改成執行 `check --ci`,檢查發現問題時掛鉤會擋下 commit。(較早的 beta 寫入的區塊只跑 `check`,標準檔被改了也回 0。)',
2574
+ hookNativeFromLegacy: 'UDS 5.x 至 6.13.1:`uds check 2>/dev/null || true`',
2575
+ hookNativeFromWithoutCi: 'UDS 6.14.0 的 beta:`check` 沒帶 `--ci`',
2576
+ hookNativeFailed: '⚠ 無法改寫 .git/hooks/pre-commit:{error}。它仍會讓每個 commit 通過——請自行把其中的 UDS 檢查那一行換成 universal-dev-standards check --ci。',
2513
2577
  newerVersion: '(你的版本比登錄庫更新:{version})',
2514
2578
  updateAvailable: '有可用更新:{current} → {latest}',
2515
2579
  // Files
@@ -2768,6 +2832,10 @@ export const messages = {
2768
2832
  categoryLine: '{category}({count})',
2769
2833
  installHint: '要装其中一个:uds update --apply --add-standard <id>(可重复该选项装多个;先加 --plan 预览)',
2770
2834
  othersLine: '上面没列出的另有 {count} 个标准,属于 `uds init` 从不安装的类别({breakdown});它们仍可用 --add-standard 指名安装。',
2835
+ recommendedTitle: '建议安装的 core 标准,尚未安装({count} 个)',
2836
+ recommendedApply: '有 {count} 个建议安装的 core 标准没装({ids});用 uds update --plan 查看。',
2837
+ checkRecommended: '有 {count} 个建议安装的 core 标准未安装({ids})— 执行 `uds update --plan` 看安装指令',
2838
+ frictionRecommended: '{count} 个建议安装的 core 标准未安装',
2771
2839
  applySummary: '上游有 {count} 个标准没装在这个项目(没有为它们改动任何文件)。',
2772
2840
  applyHint: '查看:uds update --plan 安装其中一个:uds update --apply --add-standard <id>',
2773
2841
  checkLine: '上游有 {count} 个标准未安装 — 执行 `uds update --plan` 查看',
@@ -2995,6 +3063,26 @@ export const messages = {
2995
3063
  },
2996
3064
 
2997
3065
  // Release Mode
3066
+ // `uds init` 可选的 uds.project.yaml 步骤的提问(XSPEC-482 R13:原本每种语言都是英文)。
3067
+ projectContract: {
3068
+ confirmCreate: '要创建 uds.project.yaml(项目命令契约)吗?',
3069
+ title: '📋 项目命令契约(uds.project.yaml)',
3070
+ intro1: '告诉 UDS 这个项目如何执行标准命令(与编程语言无关)。',
3071
+ intro2: '按 Enter 接受建议值,或自行输入。留空表示跳过。',
3072
+ detected: '检测到的建议值:',
3073
+ alreadyExists: 'uds.project.yaml 已存在。',
3074
+ keptSections: '这些区段会原封不动保留:{sections}。',
3075
+ noOtherSections: '它没有其他区段。',
3076
+ updateQuestion: '要更新现有 uds.project.yaml 里的命令(test、lint、build、security)吗?{kept}',
3077
+ replaceQuestion: '现有的 uds.project.yaml 无法当作 YAML 读取,所以其中内容都无法保留。要整份替换吗?',
3078
+ skippedKeeping: '已跳过——保留现有的 uds.project.yaml',
3079
+ commandOptional: '{intent} 命令(可选):',
3080
+ commandDefault: '{intent} 命令(默认:{value}):',
3081
+ noneEntered: '没有输入任何命令——未创建 uds.project.yaml。',
3082
+ updated: '✔ uds.project.yaml 已更新(其他区段保持原样)',
3083
+ created: '✔ 已创建 uds.project.yaml',
3084
+ path: '路径:{path}'
3085
+ },
2998
3086
  releaseMode: {
2999
3087
  title: '发布模式:',
3000
3088
  description: '选择发布模式,影响版本如何发布',
@@ -3800,6 +3888,14 @@ export const messages = {
3800
3888
  hookWouldMigrate: '+ .husky/pre-commit:将把旧版 UDS 写入的那一行(它会请 npm 解析裸名称 uds,而那不是本项目)换成只执行已安装 UDS CLI 的写法。',
3801
3889
  hookLegacyKept: '⚠ .husky/pre-commit 第 {line} 行(“{text}”)会请 npm 解析裸名称 uds,而它在 npm registry 上是不相干的包。这一行不是 UDS 写入的原样,所以没有动它。请自行改成 universal-dev-standards check——需要在本项目或 PATH 上已安装 UDS CLI。',
3802
3890
  hookMigrateFailed: '⚠ 无法改写 .husky/pre-commit:{error}。请 npm 解析裸名称 uds 的那一行仍在,请自行改成 universal-dev-standards check。',
3891
+ hookNativeMigrated: '✓ .git/hooks/pre-commit:已把旧版 UDS 写入的钩子({from})换成现行版本。旧的会把检查的错误丢掉、让每个 commit 都通过;新的会在 `check --ci` 报告问题时拦下 commit。',
3892
+ hookNativeWouldMigrate: '+ .git/hooks/pre-commit:将把旧版 UDS 写入的钩子({from})换成现行版本。旧的会把检查的错误丢掉、让每个 commit 都通过;新的会在 `check --ci` 报告问题时拦下 commit。',
3893
+ hookNativeKept: '⚠ .git/hooks/pre-commit 第 {line} 行(“{text}”)会执行 UDS 检查,但不论查到什么都让 commit 通过。这个文件不是 UDS 写入的原样,所以没有动它。请自行把那一行改成 universal-dev-standards check --ci——需要在本项目或 PATH 上已安装 UDS CLI。',
3894
+ hookHuskyCiMigrated: '✓ .husky/pre-commit:UDS 区块现在执行 `check --ci`,检查发现问题时钩子会拦下 commit。(较早的 beta 写入的区块只跑 `check`,标准文件被改了也返回 0。)',
3895
+ hookHuskyCiWouldMigrate: '+ .husky/pre-commit:将把 UDS 区块改成执行 `check --ci`,检查发现问题时钩子会拦下 commit。(较早的 beta 写入的区块只跑 `check`,标准文件被改了也返回 0。)',
3896
+ hookNativeFromLegacy: 'UDS 5.x 至 6.13.1:`uds check 2>/dev/null || true`',
3897
+ hookNativeFromWithoutCi: 'UDS 6.14.0 的 beta:`check` 没带 `--ci`',
3898
+ hookNativeFailed: '⚠ 无法改写 .git/hooks/pre-commit:{error}。它仍会让每个 commit 通过——请自行把其中的 UDS 检查那一行换成 universal-dev-standards check --ci。',
3803
3899
  newerVersion: '(您有比注册表更新的版本:{version})',
3804
3900
  updateAvailable: '有可用更新:{current} → {latest}',
3805
3901
  // Files
@@ -57,7 +57,7 @@ export const hooksSourceDir = () => resolveDir(['hooks'], ['scripts', 'hooks']);
57
57
  * (`matcher: { tool: Bash }`), which would be written into settings.json
58
58
  * verbatim and never match anything.
59
59
  */
60
- function normalizeMatcher(matcher) {
60
+ export function normalizeMatcher(matcher) {
61
61
  if (typeof matcher === 'string') return matcher;
62
62
  if (matcher && typeof matcher === 'object' && typeof matcher.tool === 'string') return matcher.tool;
63
63
  return '';
package/src/mcp/server.js CHANGED
@@ -123,6 +123,9 @@ export class McpServer {
123
123
  switch (method) {
124
124
  case 'initialize':
125
125
  return this.handleInitialize(request);
126
+ case 'ping':
127
+ // MCP utility: a liveness check; the answer is an empty result (XSPEC-482 R14c).
128
+ return { jsonrpc: '2.0', id, result: {} }; // wire:mcp-ping
126
129
  case 'tools/list':
127
130
  return this.handleToolsList(request);
128
131
  case 'tools/call':
@@ -252,12 +255,15 @@ export class McpServer {
252
255
  result: toolResult,
253
256
  };
254
257
  } catch (err) {
258
+ // A tool that ran and failed (a file it needed is not there) answers with a RESULT marked `isError`, as MCP
259
+ // specifies for tool execution errors, so the model calling it can read the reason and go on. A JSON-RPC
260
+ // error is for a request the server could not take at all (XSPEC-482 R14c).
255
261
  return {
256
262
  jsonrpc: '2.0',
257
263
  id,
258
- error: {
259
- code: -32000,
260
- message: err.message,
264
+ result: {
265
+ content: [{ type: 'text', text: err.message }],
266
+ isError: true, // wire:mcp-tool-error-is-a-result
261
267
  },
262
268
  };
263
269
  }
@@ -1569,7 +1569,7 @@ export function mergeProjectConfigYaml(existing, commands) {
1569
1569
  export async function promptProjectContractStep(projectPath) {
1570
1570
  try {
1571
1571
  const wantContract = await inquirerConfirm({
1572
- message: 'Create uds.project.yaml (project command contract)?',
1572
+ message: t().projectContract.confirmCreate,
1573
1573
  default: true
1574
1574
  });
1575
1575
  if (wantContract) {
@@ -1600,22 +1600,21 @@ export async function promptProjectCommandContract(projectPath) {
1600
1600
  existing = describeProjectConfig(existingText);
1601
1601
 
1602
1602
  console.log();
1603
- console.log(chalk.yellow(' uds.project.yaml already exists.'));
1603
+ console.log(chalk.yellow(` ${t().projectContract.alreadyExists}`));
1604
1604
 
1605
1605
  const kept = existing.sections.filter(name => name !== 'commands');
1606
+ const pc = t().projectContract;
1606
1607
  const message = existing.readable
1607
- ? 'Update the commands (test, lint, build, security) in the existing uds.project.yaml? ' +
1608
- (kept.length > 0
1609
- ? `These sections are kept exactly as they are: ${kept.join(', ')}.`
1610
- : 'It has no other sections.')
1608
+ ? pc.updateQuestion.replace('{kept}', kept.length > 0
1609
+ ? pc.keptSections.replace('{sections}', kept.join(', '))
1610
+ : pc.noOtherSections)
1611
1611
  // Not YAML: nothing in it can be kept, so the question names the loss instead of hiding it.
1612
- : 'The existing uds.project.yaml cannot be read as YAML, so none of its content can be kept. ' +
1613
- 'Replace the whole file?';
1612
+ : pc.replaceQuestion;
1614
1613
 
1615
1614
  const overwrite = await inquirerConfirm({ message, default: false });
1616
1615
 
1617
1616
  if (!overwrite) {
1618
- console.log(chalk.gray(' Skipped — keeping existing uds.project.yaml'));
1617
+ console.log(chalk.gray(` ${t().projectContract.skippedKeeping}`));
1619
1618
  return false;
1620
1619
  }
1621
1620
  }
@@ -1624,13 +1623,14 @@ export async function promptProjectCommandContract(projectPath) {
1624
1623
  const hasAnySuggestion = Object.values(suggestions).some(v => v);
1625
1624
 
1626
1625
  console.log();
1627
- console.log(chalk.bold('📋 Project Command Contract (uds.project.yaml)'));
1628
- console.log(chalk.gray(' Tell UDS how to run standard commands in this project (language-agnostic).'));
1629
- console.log(chalk.gray(' Press Enter to accept a suggestion, or type your own. Leave blank to skip.'));
1626
+ const pcm = t().projectContract;
1627
+ console.log(chalk.bold(pcm.title));
1628
+ console.log(chalk.gray(` ${pcm.intro1}`));
1629
+ console.log(chalk.gray(` ${pcm.intro2}`));
1630
1630
  console.log();
1631
1631
 
1632
1632
  if (hasAnySuggestion) {
1633
- console.log(chalk.gray(' Detected suggestions:'));
1633
+ console.log(chalk.gray(` ${pcm.detected}`));
1634
1634
  for (const [intent, cmd] of Object.entries(suggestions)) {
1635
1635
  if (cmd) console.log(chalk.gray(` ${intent}: ${cmd}`));
1636
1636
  }
@@ -1644,7 +1644,7 @@ export async function promptProjectCommandContract(projectPath) {
1644
1644
  // A command the file already declares is the default, so Enter keeps it; the ecosystem guess only fills gaps.
1645
1645
  const defaultVal = existing?.commands?.[intent] || suggestions[intent] || '';
1646
1646
  const answer = await input({
1647
- message: ` ${intent} command${defaultVal ? ` (default: ${defaultVal})` : ' (optional)'}:`,
1647
+ message: ` ${defaultVal ? pcm.commandDefault.replace('{intent}', intent).replace('{value}', defaultVal) : pcm.commandOptional.replace('{intent}', intent)}`,
1648
1648
  default: defaultVal
1649
1649
  });
1650
1650
  commands[intent] = answer.trim();
@@ -1652,7 +1652,7 @@ export async function promptProjectCommandContract(projectPath) {
1652
1652
 
1653
1653
  const hasAnyCommand = Object.values(commands).some(v => v);
1654
1654
  if (!hasAnyCommand) {
1655
- console.log(chalk.gray(' No commands entered — uds.project.yaml not created.'));
1655
+ console.log(chalk.gray(` ${pcm.noneEntered}`));
1656
1656
  return false;
1657
1657
  }
1658
1658
 
@@ -1665,7 +1665,7 @@ export async function promptProjectCommandContract(projectPath) {
1665
1665
  writeFileSync(contractPath, content, 'utf-8');
1666
1666
 
1667
1667
  console.log();
1668
- console.log(chalk.green(merging ? ' ✔ uds.project.yaml updated (other sections kept as they were)' : ' ✔ uds.project.yaml created'));
1669
- console.log(chalk.gray(` Path: ${contractPath}`));
1668
+ console.log(chalk.green(` ${merging ? pcm.updated : pcm.created}`));
1669
+ console.log(chalk.gray(` ${pcm.path.replace('{path}', contractPath)}`));
1670
1670
  return true;
1671
1671
  }
@@ -24,12 +24,13 @@ import {
24
24
  installSkillsToMultipleAgents,
25
25
  installCommandsToMultipleAgents
26
26
  } from '../utils/skills-installer.js';
27
- import { writeManifest } from '../core/manifest.js';
27
+ import { writeManifest, mergeInstalledNames } from '../core/manifest.js';
28
28
  import { getRepositoryInfo } from '../utils/registry.js';
29
29
  import { displayLanguageToLocale } from '../utils/locale.js';
30
30
  import { computeFileHash, pruneIntegrationFileHashes } from '../utils/hasher.js';
31
31
  import { createBackup, cleanupBackups, finalizeBackup } from './backup-manager.js';
32
32
  import { bookkeepingFiles } from './install-roots.js';
33
+ import { alignRecordedVersions } from './recorded-versions.js';
33
34
 
34
35
  /**
35
36
  * @typedef {Object} ExecutionResult
@@ -179,6 +180,9 @@ export async function executePlan(projectPath, plan, manifest, options = {}) {
179
180
  // the weekly staleness scout — which reads exactly `upstream.version` — kept
180
181
  // reporting the repo as stale after a fully successful reconcile. (XSPEC-343 R2)
181
182
  if (!dryRun && results.every(r => r.success)) {
183
+ // XSPEC-475 R6: a clean reconcile leaves the skills and commands exactly as this UDS ships them (the plan covers every
184
+ // difference), so the versions recorded for them move with it - also when no file needed rewriting.
185
+ alignRecordedVersions(updatedManifest); // wire:apply-aligns-versions
182
186
  const version = getRepositoryInfo()?.standards?.version;
183
187
  if (version) {
184
188
  updatedManifest.upstream = {
@@ -418,6 +422,50 @@ function executeMigrateBlock(projectPath, action, manifest) {
418
422
  return { action, success: false, error: result.error };
419
423
  }
420
424
 
425
+ /**
426
+ * After a batch install that succeeded, make the manifest say what the disk now holds: the version of the skills/commands
427
+ * this UDS ships, and the names installed (added to the ones already recorded). XSPEC-475 R6.
428
+ * @param {Object} manifest
429
+ * @param {'skills'|'commands'} kind
430
+ * @param {Object} installResult - from installSkills/CommandsToMultipleAgents
431
+ */
432
+ function recordInstalledSet(manifest, kind, installResult) {
433
+ const shipped = getRepositoryInfo()?.skills?.version;
434
+ manifest[kind] = { ...(manifest[kind] || {}) };
435
+ if (shipped) manifest[kind].version = shipped;
436
+ manifest[kind].names = mergeInstalledNames(manifest[kind].names, installResult);
437
+ }
438
+
439
+ /**
440
+ * The outcome of one skill or command action after its batch ran (XSPEC-482 R10).
441
+ *
442
+ * The batch installer answers once for all of them. The old code copied that one answer onto every action and gave
443
+ * no reason, so a read-only skills folder printed "8 failed" and then eight lines of "Unknown error" with neither a path nor a
444
+ * cause, and a skill that had installed fine was counted as failed too. Here each action is judged on its own: it fails when
445
+ * the installer recorded an error for its name (or for its whole agent), and the error says which path and why.
446
+ *
447
+ * @param {Object} action - plan action (category 'skill' or 'command')
448
+ * @param {Object} installResult - from installSkills/CommandsToMultipleAgents
449
+ * @param {'skill'|'command'} kind
450
+ * @returns {{ action: Object, success: boolean, error?: string }}
451
+ */
452
+ export function judgeBatchAction(action, installResult, kind) {
453
+ const meta = action.details?.metadata;
454
+ const name = kind === 'skill' ? meta?.skillName : meta?.commandName;
455
+ const installs = (installResult.installations || []).filter(i => !meta?.agent || i.agent === meta.agent);
456
+ const reasons = [];
457
+ for (const inst of installs) {
458
+ if (inst.error) reasons.push(inst.error);
459
+ for (const e of inst.errors || []) {
460
+ if (e && e[kind] === name && e.error) reasons.push(e.error);
461
+ }
462
+ }
463
+ if (reasons.length > 0) return { action, success: false, error: `${action.path}: ${reasons[0]}` };
464
+ if (installResult.success) return { action, success: true };
465
+ if (installs.some(i => (i.installed || []).includes(name))) return { action, success: true };
466
+ return { action, success: false, error: `${action.path}: the installer did not install ${kind} "${name}" and gave no reason` };
467
+ }
468
+
421
469
  /**
422
470
  * Batch execute skill installations.
423
471
  */
@@ -477,13 +525,20 @@ async function executeSkillBatch(projectPath, skillActions, manifest) {
477
525
  if (installResult.allFileHashes) {
478
526
  Object.assign(manifest.skillHashes, installResult.allFileHashes);
479
527
  }
528
+ // XSPEC-475 R6: the skill files were just rewritten to what this UDS ships, so the records that describe them
529
+ // are brought to match. They were left at the old version and name list (the 6.11.0 -> 6.14 upgrade rewrote about
530
+ // 200 files and still recorded 6.11.0 and no `comprehension-ladder`), and the second command `--skills` was the
531
+ // only way to make the manifest agree with the disk.
532
+ if (installResult.success) {
533
+ recordInstalledSet(manifest, 'skills', installResult); // wire:apply-records-skills
534
+ }
480
535
 
481
536
  for (const action of toInstall) {
482
- results.push({ action, success: installResult.success });
537
+ results.push(judgeBatchAction(action, installResult, 'skill')); // wire:skill-batch-names-its-failures
483
538
  }
484
539
  } catch (err) {
485
540
  for (const action of toInstall) {
486
- results.push({ action, success: false, error: err.message });
541
+ results.push({ action, success: false, error: `${action.path}: ${err.message}` });
487
542
  }
488
543
  }
489
544
  }
@@ -564,13 +619,16 @@ async function executeCommandBatch(projectPath, commandActions, manifest) {
564
619
  // neither line.
565
620
  Object.assign(manifest.commandHashes, installResult.allFileHashes);
566
621
  }
622
+ if (installResult.success) {
623
+ recordInstalledSet(manifest, 'commands', installResult); // wire:apply-records-commands (XSPEC-475 R6)
624
+ }
567
625
 
568
626
  for (const action of toInstall) {
569
- results.push({ action, success: installResult.success });
627
+ results.push(judgeBatchAction(action, installResult, 'command'));
570
628
  }
571
629
  } catch (err) {
572
630
  for (const action of toInstall) {
573
- results.push({ action, success: false, error: err.message });
631
+ results.push({ action, success: false, error: `${action.path}: ${err.message}` });
574
632
  }
575
633
  }
576
634
  }
@@ -0,0 +1,49 @@
1
+ /**
2
+ * The version the manifest records for the skills and the commands (XSPEC-475 R6).
3
+ *
4
+ * When a reconcile leaves nothing to do (or does everything cleanly), the skill and command files are exactly what this UDS
5
+ * ships, so the version recorded for them is the shipped one. It was left at the version of the UDS that installed them, and
6
+ * `uds check` went on saying "Commands: v6.11.0 -> v6.14..." for a project that was in fact current.
7
+ *
8
+ * @module reconciler/recorded-versions
9
+ */
10
+
11
+ import { getRepositoryInfo } from '../utils/registry.js';
12
+
13
+ /**
14
+ * Set `skills.version` and `commands.version` to the shipped version for each that is installed (not a marketplace install).
15
+ * Mutates and returns `manifest`; `changed` says whether anything differed.
16
+ * @param {Object} manifest
17
+ * @returns {{ manifest: Object, changed: boolean }}
18
+ */
19
+ export function alignRecordedVersions(manifest) {
20
+ const shipped = getRepositoryInfo()?.skills?.version;
21
+ let changed = false;
22
+ if (!shipped) return { manifest, changed };
23
+ for (const kind of ['skills', 'commands']) {
24
+ const record = manifest[kind];
25
+ if (record?.installed === true && record.location !== 'marketplace' && record.version !== shipped) {
26
+ manifest[kind] = { ...record, version: shipped }; // [mutation-anchor:align-version]
27
+ changed = true;
28
+ }
29
+ }
30
+ return { manifest, changed };
31
+ }
32
+
33
+ /**
34
+ * Set `upstream.version` (and the date it was recorded) to the standards version this UDS ships (XSPEC-482 R6).
35
+ *
36
+ * The same reasoning as for skills and commands above: when a reconcile finds nothing to do, every standard file is exactly
37
+ * what this UDS ships, so the version recorded for the standards is the shipped one. Only a reconcile that EXECUTED a plan
38
+ * recorded it, so a project whose files were already current kept the version of the UDS that installed them; it surfaced
39
+ * once `uds init` left a project with nothing for the first `--apply` to do (the XSPEC-382 R5 end-to-end test seeds an old
40
+ * version and expects `--apply` to move it).
41
+ * @param {Object} manifest
42
+ * @returns {{ manifest: Object, changed: boolean }}
43
+ */
44
+ export function alignUpstreamVersion(manifest) {
45
+ const shipped = getRepositoryInfo()?.standards?.version;
46
+ if (!shipped || !manifest?.upstream || manifest.upstream.version === shipped) return { manifest, changed: false };
47
+ manifest.upstream = { ...manifest.upstream, version: shipped, installed: new Date().toISOString().split('T')[0] };
48
+ return { manifest, changed: true };
49
+ }
@@ -1,7 +1,7 @@
1
1
  import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, rmdirSync } from 'fs';
2
2
  import { join, basename } from 'path';
3
3
  import { proveUnchanged, RECORD_KINDS, RECORDS_KEY, isRealDirectory } from '../core/install-records.js';
4
- import { stripUdsHookBlock } from '../utils/git-hooks.js';
4
+ import { stripUdsHookBlock, classifyNativePreCommitHook } from '../utils/git-hooks.js';
5
5
  import {
6
6
  collectHookConfigs, standardsSourceDir, hooksSourceDir,
7
7
  CODEX_HOOK_SCRIPT, GEMINI_HOOK_SCRIPT, AGY_HOOK_SCRIPT,
@@ -427,6 +427,14 @@ export function uninstallHook(projectPath, options = {}) {
427
427
  if (!dryRun) unlinkSync(nativeHookPath);
428
428
  result.removed.push(`.git/hooks/pre-commit (UDS native hook, file removed — ${proof.why})`);
429
429
  result.deletedPaths.push('.git/hooks/pre-commit');
430
+ } else if (classifyNativePreCommitHook(content)) { // wire:uninstall-removes-known-native-hook
431
+ // XSPEC-482 R8: no install record (an older UDS wrote it, and old versions recorded nothing), but the file
432
+ // is byte for byte a hook UDS has written - the always-pass hook of 5.x to 6.13.1, or one of the later ones.
433
+ // Exact text is the proof; deleting only the matching lines used to leave a script behind that still
434
+ // printed "Pre-commit checks passed" and checked nothing.
435
+ if (!dryRun) unlinkSync(nativeHookPath);
436
+ result.removed.push('.git/hooks/pre-commit (UDS native hook, file removed - its text is exactly what UDS writes, so nothing of yours is in it)');
437
+ result.deletedPaths.push('.git/hooks/pre-commit');
430
438
  } else if (!NATIVE_UDS_LINE.test(content) && !stripUdsHookBlock(content).removed) {
431
439
  result.skipped.push('.git/hooks/pre-commit (no UDS lines found)');
432
440
  } else {
@@ -1,5 +1,5 @@
1
1
  import { existsSync, rmSync, rmdirSync, readdirSync, unlinkSync } from 'fs';
2
- import { dirname, join, relative, isAbsolute } from 'path';
2
+ import { dirname, join, relative, isAbsolute, resolve } from 'path';
3
3
  import {
4
4
  getSkillsDirForAgent,
5
5
  getCommandsDirForAgent
@@ -148,10 +148,17 @@ function processInstallation(install, type, projectPath, manifest, options, resu
148
148
  if (existsSync(marker)) rmSync(marker, { force: true });
149
149
  }
150
150
  // Folders UDS emptied, deepest first, then the installation folder itself.
151
+ // The installation folder is compared as a resolved path: `dir` carries the trailing slash the path table
152
+ // gives it (`.gemini/commands/`) and `dirname(file)` does not, so the old `d !== dir` was true for the
153
+ // installation folder itself. It was removed in this loop, `removeIfEmpty(dir)` below then found nothing to
154
+ // remove and answered "not gone": the line said "folder kept" for a folder that was deleted, and the tool's
155
+ // own parent (`.gemini/`, `.opencode/`) was never looked at, so an empty one stayed (XSPEC-482 R8).
156
+ const installDir = resolve(dir);
151
157
  for (const d of [...touched].sort((a, b) => b.length - a.length)) {
152
- if (d !== dir) removeIfEmpty(d);
158
+ if (resolve(d) !== installDir) removeIfEmpty(d);
153
159
  }
154
- const gone = removeIfEmpty(dir);
160
+ removeIfEmpty(dir);
161
+ const gone = !existsSync(dir); // wire:uninstall-folder-removed-is-reported
155
162
  // XSPEC-475 R5(d): the tool's own folder (`.claude/`, `.codex/` ...) that held only what UDS wrote is empty now; an
156
163
  // empty `.claude/` left in the project is a trace of UDS. Only an EMPTY folder inside the project, never the project
157
164
  // root, and never a user-level folder.
@@ -35,7 +35,7 @@ function breakdown(byCategory) {
35
35
  */
36
36
  export function printAvailableStandardsSection(manifest, { phase }) {
37
37
  const msg = t().availableStandards;
38
- const { offered, notOffered, notOfferedByCategory } = getAvailableStandards(manifest);
38
+ const { offered, notOffered, recommended } = getAvailableStandards(manifest);
39
39
 
40
40
  console.log();
41
41
  if (offered.length === 0) {
@@ -57,20 +57,41 @@ export function printAvailableStandardsSection(manifest, { phase }) {
57
57
  console.log(chalk.gray(` ${msg.installHint}`));
58
58
  }
59
59
 
60
- if (notOffered.length > 0) {
61
- console.log(chalk.gray(fill(msg.othersLine, { count: notOffered.length, breakdown: breakdown(notOfferedByCategory) })));
60
+ // XSPEC-475 R9: the recommended core standards, one by one, each with the command that installs it.
61
+ if (recommended.length > 0) {
62
+ if (phase === 'apply') {
63
+ console.log(chalk.cyan(fill(msg.recommendedApply, { count: recommended.length, ids: recommended.map((s) => s.id).join(', ') })));
64
+ } else {
65
+ console.log(chalk.cyan(fill(msg.recommendedTitle, { count: recommended.length })));
66
+ for (const std of recommended) {
67
+ console.log(` ${chalk.green(std.id)} ${chalk.gray(`— ${std.description}`)}`);
68
+ console.log(chalk.gray(` uds update --apply --add-standard ${std.id}`)); // [mutation-anchor:recommended-install-command]
69
+ }
70
+ }
71
+ }
72
+
73
+ // "Not listed above" counts what is NOT listed: the recommended ones were listed one by one, so they are taken out of the
74
+ // count and of the breakdown (XSPEC-475 R9; it said 95 when 2 of the 95 were on the lines above).
75
+ const unlisted = notOffered.filter((n) => !recommended.some((r) => r.id === n.id)); // [mutation-anchor:unlisted-count]
76
+ if (unlisted.length > 0) {
77
+ const byCategory = {};
78
+ for (const n of unlisted) byCategory[n.category] = (byCategory[n.category] || 0) + 1;
79
+ console.log(chalk.gray(fill(msg.othersLine, { count: unlisted.length, breakdown: breakdown(byCategory) })));
62
80
  }
63
81
  }
64
82
 
65
83
  /** `uds check`: one line, never part of the verdict. */
66
84
  export function printAvailableStandardsCheckLine(manifest) {
67
85
  const msg = t().availableStandards;
68
- const { offered } = getAvailableStandards(manifest);
86
+ const { offered, recommended } = getAvailableStandards(manifest);
69
87
  if (offered.length === 0) {
70
88
  console.log(chalk.gray(msg.checkNone));
71
89
  } else {
72
90
  console.log(chalk.cyan(fill(msg.checkLine, { count: offered.length })));
73
91
  }
92
+ if (recommended.length > 0) {
93
+ console.log(chalk.cyan(fill(msg.checkRecommended, { count: recommended.length, ids: recommended.map((s) => s.id).join(', ') })));
94
+ }
74
95
  }
75
96
 
76
97
  /**
@@ -23,6 +23,14 @@
23
23
  * "new upstream" — they were never in the offer. Why, per category, is in CATEGORY_NOTES.
24
24
  * They are still returned (with a reason) so no command can silently pretend they do not exist.
25
25
  *
26
+ * Recommended core standards (XSPEC-475 R9)
27
+ * -----------------------------------------
28
+ * 59 core standards are not installed by `uds init`, and listing all of them one by one in every `--plan` would bury the
29
+ * few an adopter asked about. A registry entry marked `"recommended": true` (today `turn-completion-integrity` and
30
+ * `pipeline-security-gates`, the two adopters named) is returned in `recommended` and listed one by one with its install
31
+ * command; the rest stay a count. `recommended` is information only: it is NOT in `offered`, so the old `uds update --yes`
32
+ * path, which installs whatever `offered` holds, does not install them (XSPEC-458: listing and installing stay apart).
33
+ *
26
34
  * Manifest fields that look like they should matter, and do not (measured 2026-10-07):
27
35
  * - `level` — a manifest written by 6.11.0 carries it only as a leftover snapshot inside
28
36
  * `integrationConfigs[<file>].level`; no code reads it to decide what to install, the generator
@@ -122,7 +130,8 @@ export function oneLineDescription(description, max = 100) {
122
130
  * @returns {{
123
131
  * offered: AvailableStandard[],
124
132
  * notOffered: Array<AvailableStandard & {reason: string, addable: boolean}>,
125
- * notOfferedByCategory: Object<string, number>
133
+ * notOfferedByCategory: Object<string, number>,
134
+ * recommended: AvailableStandard[]
126
135
  * }}
127
136
  */
128
137
  export function getAvailableStandards(manifest) {
@@ -138,7 +147,7 @@ export function getAvailableStandards(manifest) {
138
147
  const name = basename(source);
139
148
  if (installed.has(name)) continue;
140
149
 
141
- const item = { id: std.id, category: std.category, description: oneLineDescription(std.description), source, name };
150
+ const item = { id: std.id, category: std.category, description: oneLineDescription(std.description), source, name, recommended: std.recommended === true };
142
151
  if (OFFERED_CATEGORIES.includes(std.category)) {
143
152
  offered.push(item);
144
153
  } else {
@@ -152,7 +161,8 @@ export function getAvailableStandards(manifest) {
152
161
 
153
162
  const notOfferedByCategory = {};
154
163
  for (const n of notOffered) notOfferedByCategory[n.category] = (notOfferedByCategory[n.category] || 0) + 1;
155
- return { offered, notOffered, notOfferedByCategory };
164
+ const recommended = notOffered.filter((n) => n.addable && n.recommended); // [mutation-anchor:recommended-core]
165
+ return { offered, notOffered, notOfferedByCategory, recommended };
156
166
  }
157
167
 
158
168
  /** Plain edit distance, enough for "did you mean". */
@@ -52,7 +52,7 @@ export function verifyManifest(manifest, gitTagCommit, options = {}) {
52
52
  if (!manifest.commit) {
53
53
  errors.push('manifest missing commit field');
54
54
  } else if (manifest.commit !== gitTagCommit) {
55
- errors.push(`commit mismatch: manifest has "${manifest.commit}", git tag points to "${gitTagCommit}"`);
55
+ errors.push(`commit mismatch: manifest has "${manifest.commit}", the current HEAD is "${gitTagCommit}"`);
56
56
  }
57
57
 
58
58
  const recorded = manifest.checksum?.package ?? null;