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

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.
@@ -3,7 +3,7 @@
3
3
 
4
4
  id: secret-management-standards
5
5
  title: Secret Management and Credential Hygiene Standards
6
- version: "1.0.0"
6
+ version: "1.1.0"
7
7
  status: Active
8
8
  tags: [secrets, vault, kms, sops, security, rotation, credential-management]
9
9
  summary: |
@@ -67,9 +67,20 @@ requirements:
67
67
  format (AKIA[0-9A-Z]{16}), PEM private key headers (-----BEGIN .* PRIVATE KEY),
68
68
  generic API token patterns (api[_-]?key\s*[:=]\s*\S{16,}), and
69
69
  connection strings containing passwords.
70
+ How the scanners are run is governed by pipeline-security-gates
71
+ (PSG-1 to PSG-3): PSG-1 the scan output MUST NOT contain the matched
72
+ secret value (file, line and rule name only); PSG-2 a scanner that
73
+ cannot run counts as a failed gate and MUST block the commit or
74
+ pipeline; PSG-3 every detection rule the team writes itself SHOULD have
75
+ a red sample (must be caught) and a green sample (must not be
76
+ reported), executed in a test.
70
77
  level: MUST
78
+ references:
79
+ - pipeline-security-gates
71
80
  examples:
72
81
  - "`.pre-commit-config.yaml` includes `detect-secrets` hook; fails on AWS key pattern"
82
+ - "PSG-1: CI log shows `rule aws-access-key at config/dev.env:12`, never the key itself (gitleaks run with `--redact`)"
83
+ - "PSG-2: gitleaks binary missing in the CI image -> the job fails, it does not pass with no scan"
73
84
  - "CI step: `gitleaks detect --source . --exit-code 1` blocks PR merge"
74
85
  - "False positive whitelisted via `.secrets.baseline` with documented justification"
75
86
  - "Developer receives pre-commit error: 'High confidence secret detected: AWS Access Key'"
@@ -1,6 +1,6 @@
1
1
  # Secret Management and Credential Hygiene Standards
2
2
 
3
- > **Version**: 1.0.0 | **Status**: Active | **Updated**: 2026-06-17
3
+ > **Version**: 1.1.0 | **Status**: Active | **Updated**: 2026-10-12
4
4
  > **AI-optimized version**: `ai/standards/secret-management-standards.ai.yaml`
5
5
  > **Spec**: XSPEC-065 (cross-project/specs/XSPEC-065-uds-infrastructure-pack.md)
6
6
 
@@ -69,6 +69,14 @@ detected patterns: AWS access key format (`AKIA[0-9A-Z]{16}`), PEM private key
69
69
  headers (`-----BEGIN .* PRIVATE KEY`), generic API token patterns
70
70
  (`api[_-]?key\s*[:=]\s*\S{16,}`), and connection strings containing passwords.
71
71
 
72
+ How the scanners are run is governed by [`pipeline-security-gates`](./pipeline-security-gates.md), and the
73
+ three rules there apply to every scanner this requirement asks for: **PSG-1** — the scan output (terminal, CI log,
74
+ report file) MUST NOT contain the matched secret value, only the file, the line and the rule name; **PSG-2** — a
75
+ scanner that cannot run (not installed, crashed, no network for its rules) counts as a failed gate and MUST block the
76
+ commit or the pipeline, never let it through; **PSG-3** — every detection rule the team writes itself SHOULD have one
77
+ sample that must be caught (red) and one that must not be reported (green), executed in a test. The four minimum
78
+ patterns above are the rules PSG-3 applies to when a team writes its own.
79
+
72
80
  ### REQ-004 — Secret Injection
73
81
 
74
82
  Secrets MUST be injected into application processes via environment variables or
@@ -91,6 +99,9 @@ secrets as read-only volumes with restrictive file permissions (0400 or 0600).
91
99
 
92
100
  - **`iac-design-principles`** — secret backends (Vault/KMS state) are themselves
93
101
  versioned, access-controlled infrastructure.
102
+ - **`pipeline-security-gates`** — PSG-1 to PSG-3 govern how the scanners of REQ-003 are run (no secret value in
103
+ their output, a scanner that cannot run blocks, red and green samples for self-written rules); the two standards
104
+ point at each other.
94
105
  - **`audit-trail`** — rotation, access, and injection events are auditable
95
106
  operations (REQ-002 mandates logging rotation events).
96
107
  - **`pii-classification`** — credentials guarding TIER-1 PII inherit the strictest
@@ -107,4 +118,5 @@ secrets as read-only volumes with restrictive file permissions (0400 or 0600).
107
118
 
108
119
  | Version | Date | Changes |
109
120
  |---------|------|---------|
121
+ | v1.1.0 | 2026-10-12 | REQ-003 points to `pipeline-security-gates` PSG-1 to PSG-3 for how the scanners are run; integration section lists the cross-reference (XSPEC-475 OQ3) |
110
122
  | v1.0.0 | 2026-06-17 | Initial — REQ-001~004: secret source options, rotation policy, hardcoded-secret prevention, secret injection (XSPEC-065) |
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  source: ../../CHANGELOG.md
3
- source_version: 6.14.0-beta.11
4
- translation_version: 6.14.0-beta.11
3
+ source_version: 6.14.0-beta.12
4
+ translation_version: 6.14.0-beta.12
5
5
  last_synced: 2026-10-12
6
6
  status: current
7
7
  ---
@@ -15,7 +15,7 @@ status: current
15
15
 
16
16
  > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
17
17
 
18
- **版本**: 6.14.0-beta.11 (Pre-release) | **发布日期**: 2026-10-10 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
18
+ **版本**: 6.14.0-beta.12 (Pre-release) | **发布日期**: 2026-10-10 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
19
19
 
20
20
  语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流,确保不同技术栈之间的一致性、质量和可维护性。
21
21
 
@@ -14,7 +14,7 @@ status: current
14
14
  <!-- UDS_SUPPORTED_VERSIONS_START -->
15
15
  | 版本 | 支持状态 |
16
16
  |------|--------|
17
- | 6.14.0-beta.11 | ✅ 预发布版本 |
17
+ | 6.14.0-beta.12 | ✅ 预发布版本 |
18
18
  | 6.13.1 | ✅ 最新正式版 |
19
19
  | < 6.0.0 | ❌ 已终止支持 |
20
20
  <!-- UDS_SUPPORTED_VERSIONS_END -->
@@ -557,7 +557,7 @@
557
557
  | `runbook` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
558
558
  | `sast-advanced` | 1.0.0 | This standard defines Advanced Static Application Security Testing (SAST) practi |
559
559
  | `schema-evolution` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
560
- | `secret-management-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
560
+ | `secret-management-standards` | 1.1.0 | **Status**: Active | **Updated**: 2026-10-12 | |
561
561
  | `secure-op` | - | |
562
562
  | `security-decision` | - | |
563
563
  | `security-standards` | 1.1.0 | This standard defines comprehensive security guidelines for software development |
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  source: ../../CHANGELOG.md
3
- source_version: 6.14.0-beta.11
4
- translation_version: 6.14.0-beta.11
3
+ source_version: 6.14.0-beta.12
4
+ translation_version: 6.14.0-beta.12
5
5
  last_synced: 2026-10-12
6
6
  status: current
7
7
  ---
@@ -15,7 +15,7 @@ status: current
15
15
 
16
16
  > **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
17
17
 
18
- **版本**: 6.14.0-beta.11 (Pre-release) | **發布日期**: 2026-10-10 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
18
+ **版本**: 6.14.0-beta.12 (Pre-release) | **發布日期**: 2026-10-10 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
19
19
 
20
20
  語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流,確保不同技術堆疊之間的一致性、品質和可維護性。
21
21
 
@@ -14,7 +14,7 @@ status: current
14
14
  <!-- UDS_SUPPORTED_VERSIONS_START -->
15
15
  | 版本 | 支援狀態 |
16
16
  |------|--------|
17
- | 6.14.0-beta.11 | ✅ 預發布版本 |
17
+ | 6.14.0-beta.12 | ✅ 預發布版本 |
18
18
  | 6.13.1 | ✅ 最新正式版 |
19
19
  | < 6.0.0 | ❌ 已終止支援 |
20
20
  <!-- UDS_SUPPORTED_VERSIONS_END -->
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  source: ../../../core/secret-management-standards.md
3
- source_version: 1.0.0
4
- translation_version: 1.0.0
5
- last_synced: 2026-07-30
6
- source_hash: d8efae1ed265
3
+ source_version: 1.1.0
4
+ translation_version: 1.1.0
5
+ last_synced: 2026-10-12
6
+ source_hash: 0d663eb39b8a
7
7
  status: current
8
8
  ---
9
9
 
@@ -65,6 +65,12 @@ staged 檔案,偵測到 pattern 即封鎖 commit;(2) **CI 管線掃描**—
65
65
  (`AKIA[0-9A-Z]{16}`)、PEM 私鑰標頭(`-----BEGIN .* PRIVATE KEY`)、通用 API token
66
66
  pattern(`api[_-]?key\s*[:=]\s*\S{16,}`),以及含密碼的連線字串。
67
67
 
68
+ 掃描器如何執行由 [`pipeline-security-gates`](./pipeline-security-gates.md) 規範,其中三條規則適用於本需求要求的每個
69
+ 掃描器:**PSG-1**——掃描輸出(終端機、CI 紀錄、報告檔)MUST NOT 包含被匹配到的機密值本身,只能指出檔案、行號與規則名稱;
70
+ **PSG-2**——無法執行的掃描器(未安裝、崩潰、規則無法取得)視同閘門失敗,MUST 阻斷 commit 或 pipeline,不得放行;
71
+ **PSG-3**——團隊自己撰寫的每條偵測規則 SHOULD 有一個必須被抓到(紅)與一個不得被誤報(綠)的樣本,並在測試中執行。
72
+ 上述四種最低 pattern 即是團隊自寫規則時 PSG-3 所適用的規則。
73
+
68
74
  ### REQ-004 — 機密注入
69
75
 
70
76
  機密 MUST 僅透過環境變數或掛載檔案注入應用程式程序。透過命令列參數傳遞機密為
@@ -85,6 +91,7 @@ volume,並使用限制性檔案權限(0400 或 0600)。
85
91
 
86
92
  - **`iac-design-principles`**——機密後端(Vault/KMS 狀態)本身即是版本化、受存取
87
93
  控制的基礎設施。
94
+ - **`pipeline-security-gates`**——PSG-1~PSG-3 規範 REQ-003 掃描器的執行方式(輸出不含機密值、掃描器跑不起來即阻斷、自寫規則要有紅綠樣本);兩份標準互相指向。
88
95
  - **`audit-trail`**——輪替、存取與注入事件為可稽核操作(REQ-002 要求記錄輪替事件)。
89
96
  - **`pii-classification`**——守護 TIER-1 PII 的憑證承襲最嚴格的處理控制。
90
97
  - **`security-standards`**——本標準是更廣安全基線的憑證衛生面向。
@@ -98,4 +105,5 @@ volume,並使用限制性檔案權限(0400 或 0600)。
98
105
 
99
106
  | 版本 | 日期 | 變更 |
100
107
  |------|------|------|
108
+ | v1.1.0 | 2026-10-12 | REQ-003 指向 `pipeline-security-gates` 的 PSG-1~PSG-3(掃描器的執行方式);整合章節列出交叉引用(XSPEC-475 OQ3) |
101
109
  | v1.0.0 | 2026-06-17 | 初版——REQ-001~004:機密來源選項、輪替政策、硬編碼機密防護、機密注入(XSPEC-065) |
@@ -557,7 +557,7 @@
557
557
  | `runbook` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
558
558
  | `sast-advanced` | 1.0.0 | This standard defines Advanced Static Application Security Testing (SAST) practi |
559
559
  | `schema-evolution` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
560
- | `secret-management-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
560
+ | `secret-management-standards` | 1.1.0 | **Status**: Active | **Updated**: 2026-10-12 | |
561
561
  | `secure-op` | - | |
562
562
  | `security-decision` | - | |
563
563
  | `security-standards` | 1.1.0 | This standard defines comprehensive security guidelines for software development |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "universal-dev-standards",
3
- "version": "6.14.0-beta.11",
3
+ "version": "6.14.0-beta.12",
4
4
  "description": "CLI tool for adopting Universal Development Standards",
5
5
  "keywords": [
6
6
  "documentation",
@@ -146,7 +146,9 @@ export async function specListCommand(options = {}) {
146
146
  // default (XSPEC-456 R5): an SDD spec whose header could not be read used to be listed as `draft`.
147
147
  const unparsed = t('spec.statusUnparsed', 'format: SDD (status not parsed)');
148
148
  const statusLabel = (spec) => spec.status ?? unparsed;
149
- const statusWidth = Math.max(12, ...specs.map((spec) => statusLabel(spec).length + 1));
149
+ // XSPEC-475 R8: the width follows the statuses that were READ. The "not parsed" sentence is longer than any status, and it
150
+ // used to stretch the whole column (and the rule under it) for every row because of one spec whose header could not be read.
151
+ const statusWidth = Math.max(12, ...specs.filter((spec) => spec.status).map((spec) => spec.status.length + 1)); // [mutation-anchor:status-width]
150
152
  const ruleWidth = 70 + (statusWidth - 12);
151
153
 
152
154
  console.log(chalk.gray('─'.repeat(ruleWidth)));
@@ -169,7 +171,7 @@ export async function specListCommand(options = {}) {
169
171
 
170
172
  console.log(
171
173
  spec.id.slice(0, 34).padEnd(35) +
172
- statusColor(statusLabel(spec).padEnd(statusWidth)) +
174
+ statusColor(statusLabel(spec).padEnd(Math.max(statusWidth, statusLabel(spec).length + 1))) +
173
175
  (spec.type ?? '-').padEnd(10) +
174
176
  spec.title.slice(0, 25)
175
177
  );
@@ -76,6 +76,7 @@ import {
76
76
  cleanupBackups
77
77
  } from '../reconciler/index.js';
78
78
  import { stepWritePaths } from '../reconciler/install-roots.js';
79
+ import { alignRecordedVersions } from '../reconciler/recorded-versions.js';
79
80
  import { restoreSingleFile } from './check.js';
80
81
  import { guardAgainstSelfAdoption } from '../utils/detect-self-adoption.js';
81
82
  import { resolveIntegrationFile, SUPPORTED_AI_TOOLS, getToolFormat } from '../core/constants.js';
@@ -3702,7 +3703,9 @@ async function handleReconcile(projectPath, options, { force, addStandards = []
3702
3703
  // XSPEC-454 R2: nothing to apply, but the manifest may still list skill files UDS never installed
3703
3704
  // (they only ever get corrected by a write, and an up-to-date project has none coming).
3704
3705
  const current = readManifest(projectPath);
3705
- if (current && (pruneForeignSkillHashes(current).length + pruneForeignCommandHashes(current).length) > 0) writeManifest(current, projectPath);
3706
+ // XSPEC-475 R6: nothing to apply means the files are what this UDS ships; the recorded versions say so too.
3707
+ const aligned = current ? alignRecordedVersions(current).changed : false; // wire:up-to-date-aligns-versions
3708
+ if (current && ((pruneForeignSkillHashes(current).length + pruneForeignCommandHashes(current).length) > 0 || aligned)) writeManifest(current, projectPath);
3706
3709
  console.log(chalk.green('Everything is up to date. No changes needed.'));
3707
3710
  // XSPEC-458 R2: "up to date" is about the files UDS manages; say what UDS ships that is not managed here.
3708
3711
  printAvailableStandardsSection(planResult.manifest, { phase: 'apply' });
@@ -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',
@@ -1402,6 +1406,10 @@ export const messages = {
1402
1406
  categoryLine: '{category}({count})',
1403
1407
  installHint: '要裝其中一個:uds update --apply --add-standard <id>(可重複旗標裝多個;先加 --plan 預覽)',
1404
1408
  othersLine: '上面沒列出的另有 {count} 個標準,屬於 `uds init` 從不安裝的類別({breakdown});它們仍可用 --add-standard 指名安裝。',
1409
+ recommendedTitle: '建議安裝的 core 標準,尚未安裝({count} 個)',
1410
+ recommendedApply: '有 {count} 個建議安裝的 core 標準沒裝({ids});用 uds update --plan 查看。',
1411
+ checkRecommended: '有 {count} 個建議安裝的 core 標準未安裝({ids})— 執行 `uds update --plan` 看安裝指令',
1412
+ frictionRecommended: '{count} 個建議安裝的 core 標準未安裝',
1405
1413
  applySummary: '上游有 {count} 個標準沒裝在這個專案(沒有為它們改動任何檔案)。',
1406
1414
  applyHint: '查看:uds update --plan 安裝其中一個:uds update --apply --add-standard <id>',
1407
1415
  checkLine: '上游有 {count} 個標準未安裝 — 執行 `uds update --plan` 查看',
@@ -2768,6 +2776,10 @@ export const messages = {
2768
2776
  categoryLine: '{category}({count})',
2769
2777
  installHint: '要装其中一个:uds update --apply --add-standard <id>(可重复该选项装多个;先加 --plan 预览)',
2770
2778
  othersLine: '上面没列出的另有 {count} 个标准,属于 `uds init` 从不安装的类别({breakdown});它们仍可用 --add-standard 指名安装。',
2779
+ recommendedTitle: '建议安装的 core 标准,尚未安装({count} 个)',
2780
+ recommendedApply: '有 {count} 个建议安装的 core 标准没装({ids});用 uds update --plan 查看。',
2781
+ checkRecommended: '有 {count} 个建议安装的 core 标准未安装({ids})— 执行 `uds update --plan` 看安装指令',
2782
+ frictionRecommended: '{count} 个建议安装的 core 标准未安装',
2771
2783
  applySummary: '上游有 {count} 个标准没装在这个项目(没有为它们改动任何文件)。',
2772
2784
  applyHint: '查看:uds update --plan 安装其中一个:uds update --apply --add-standard <id>',
2773
2785
  checkLine: '上游有 {count} 个标准未安装 — 执行 `uds update --plan` 查看',
@@ -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,20 @@ 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
+
421
439
  /**
422
440
  * Batch execute skill installations.
423
441
  */
@@ -477,6 +495,13 @@ async function executeSkillBatch(projectPath, skillActions, manifest) {
477
495
  if (installResult.allFileHashes) {
478
496
  Object.assign(manifest.skillHashes, installResult.allFileHashes);
479
497
  }
498
+ // XSPEC-475 R6: the skill files were just rewritten to what this UDS ships, so the records that describe them
499
+ // are brought to match. They were left at the old version and name list (the 6.11.0 -> 6.14 upgrade rewrote about
500
+ // 200 files and still recorded 6.11.0 and no `comprehension-ladder`), and the second command `--skills` was the
501
+ // only way to make the manifest agree with the disk.
502
+ if (installResult.success) {
503
+ recordInstalledSet(manifest, 'skills', installResult); // wire:apply-records-skills
504
+ }
480
505
 
481
506
  for (const action of toInstall) {
482
507
  results.push({ action, success: installResult.success });
@@ -564,6 +589,9 @@ async function executeCommandBatch(projectPath, commandActions, manifest) {
564
589
  // neither line.
565
590
  Object.assign(manifest.commandHashes, installResult.allFileHashes);
566
591
  }
592
+ if (installResult.success) {
593
+ recordInstalledSet(manifest, 'commands', installResult); // wire:apply-records-commands (XSPEC-475 R6)
594
+ }
567
595
 
568
596
  for (const action of toInstall) {
569
597
  results.push({ action, success: installResult.success });
@@ -0,0 +1,31 @@
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
+ }
@@ -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". */
@@ -51,15 +51,28 @@ function withUncasedLettersAsLowercase(text) {
51
51
  return text.replace(/\p{L}/gu, (ch) => (ch.toLowerCase() === ch.toUpperCase() ? 'a' : ch));
52
52
  }
53
53
 
54
+ /** Compare dotted numeric versions ("1.0.0" < "2.0.0"); a missing or non-numeric part counts as 0. */
55
+ function compareVersions(a, b) {
56
+ const part = (v) => String(v ?? '0').split(/[.-]/).map((n) => Number.parseInt(n, 10) || 0);
57
+ const [x, y] = [part(a), part(b)];
58
+ for (let i = 0; i < Math.max(x.length, y.length); i++) {
59
+ const d = (x[i] ?? 0) - (y[i] ?? 0);
60
+ if (d !== 0) return d < 0 ? -1 : 1;
61
+ }
62
+ return 0;
63
+ }
64
+
54
65
  /**
55
66
  * The commit types the project's installed option files allow. An option file belongs to this standard when
56
67
  * its `meta.parent` is `commit-message`. Installed projects keep option files flat in `.standards/options/`
57
68
  * (`english.ai.yaml`); a checkout of UDS itself nests them (`.standards/options/commit-message/`). Both are read.
58
69
  * @param {string} standardsDir - `<project>/.standards`
59
- * @returns {{ types: string[], source: string }}
70
+ * @param {{ shippedRoot?: string|null }} [opts] - the folder holding the option files this CLI ships (`<root>/ai/options/commit-message/`)
71
+ * @returns {{ types: string[], source: string, stale: Array<{id: string, installed: string, shipped: string}> }}
60
72
  */
61
- export function allowedCommitTypes(standardsDir) {
73
+ export function allowedCommitTypes(standardsDir, { shippedRoot = null } = {}) {
62
74
  const found = new Set();
75
+ const stale = [];
63
76
  const optionsDir = path.join(standardsDir, 'options');
64
77
  for (const dir of [optionsDir, path.join(optionsDir, 'commit-message')]) {
65
78
  let names = [];
@@ -72,7 +85,19 @@ export function allowedCommitTypes(standardsDir) {
72
85
  try {
73
86
  const doc = yaml.load(fs.readFileSync(path.join(dir, name), 'utf-8'));
74
87
  if (doc?.meta?.parent !== 'commit-message') continue;
75
- for (const entry of doc.types || []) {
88
+ // XSPEC-475 R7: an installed option file that is OLDER than the one this CLI ships is judged by the shipped one, and
89
+ // the caller is told. After a CLI upgrade and before `uds update --apply` the installed file still has the old rules
90
+ // (traditional-chinese 1.0.0 listed Chinese types), and judging by it gave the opposite of the current answer without a word.
91
+ let rules = doc;
92
+ const shippedFile = shippedRoot && doc.id ? path.join(shippedRoot, 'ai', 'options', 'commit-message', `${doc.id}.ai.yaml`) : null;
93
+ if (shippedFile && fs.existsSync(shippedFile)) {
94
+ const shipped = yaml.load(fs.readFileSync(shippedFile, 'utf-8'));
95
+ if (compareVersions(doc.meta.version, shipped?.meta?.version) < 0) { // [mutation-anchor:installed-option-older]
96
+ rules = shipped;
97
+ stale.push({ id: doc.id, installed: String(doc.meta.version ?? 'unknown'), shipped: String(shipped.meta.version) });
98
+ }
99
+ }
100
+ for (const entry of rules.types || []) {
76
101
  if (entry && typeof entry.type === 'string') found.add(entry.type);
77
102
  }
78
103
  } catch {
@@ -80,8 +105,8 @@ export function allowedCommitTypes(standardsDir) {
80
105
  }
81
106
  }
82
107
  }
83
- if (found.size === 0) return { types: FALLBACK_TYPES, source: 'the Conventional Commits set, because no commit-message option file is installed' };
84
- return { types: [...found], source: '.standards/options' };
108
+ if (found.size === 0) return { types: FALLBACK_TYPES, source: 'the Conventional Commits set, because no commit-message option file is installed', stale };
109
+ return { types: [...found], source: stale.length > 0 ? ".standards/options, with the CLI's current rules for the option file(s) listed as out of date" : '.standards/options', stale };
85
110
  }
86
111
 
87
112
  /** The `validator` pattern of a rule in the standard, as a RegExp, or null when there is none. */
@@ -99,12 +124,13 @@ function ruleValidator(standardConfig, ruleId) {
99
124
  * @param {Object} standardConfig - the parsed commit-message standard
100
125
  * @param {string} input - the commit message (only the first line is the header)
101
126
  * @param {{ standardsDir: string }} context
102
- * @returns {{ verdict: 'pass' | 'fail', findings: string[], checked: string[], notChecked: string[] }}
127
+ * @returns {{ verdict: 'pass' | 'fail', findings: string[], checked: string[], notChecked: string[], notes: string[] }}
103
128
  */
104
- export function judgeCommitMessage(standardConfig, input, { standardsDir }) {
129
+ export function judgeCommitMessage(standardConfig, input, { standardsDir, shippedRoot = null }) {
105
130
  const findings = [];
106
131
  const checked = [];
107
132
  const notChecked = [];
133
+ const notes = [];
108
134
 
109
135
  const header = String(input).replace(/\r\n/g, '\n').split('\n')[0];
110
136
  const match = HEADER.exec(header);
@@ -114,7 +140,10 @@ export function judgeCommitMessage(standardConfig, input, { standardsDir }) {
114
140
  findings.push('The first line is not in the form <type>(<scope>): <subject> (scope is optional).');
115
141
  } else {
116
142
  const { type, scope, subject } = match.groups;
117
- const { types, source } = allowedCommitTypes(standardsDir);
143
+ const { types, source, stale } = allowedCommitTypes(standardsDir, { shippedRoot });
144
+ for (const o of stale) {
145
+ notes.push(`The installed option file "${o.id}" is version ${o.installed}, older than the ${o.shipped} this CLI ships, so this message was judged by the CLI's current rules. Run \`uds update --apply\` to bring the installed option file up to date.`);
146
+ }
118
147
 
119
148
  checked.push(`type is one of: ${types.join(', ')} (from ${source})`);
120
149
  if (!types.includes(type)) {
@@ -151,5 +180,5 @@ export function judgeCommitMessage(standardConfig, input, { standardsDir }) {
151
180
  notChecked.push('rule imperative-mood (the standard gives no machine-checkable pattern)');
152
181
  notChecked.push('rule no-mixed-changes and the commit language option');
153
182
 
154
- return { verdict: findings.length === 0 ? 'pass' : 'fail', findings, checked, notChecked };
183
+ return { verdict: findings.length === 0 ? 'pass' : 'fail', findings, checked, notChecked, notes };
155
184
  }
@@ -55,18 +55,30 @@ export function detectFrictions(projectPath, manifest) {
55
55
  * @returns {Array}
56
56
  */
57
57
  function detectAvailableStandards(manifest) {
58
- const { offered } = getAvailableStandards(manifest);
59
- if (offered.length === 0) return [];
60
-
58
+ const { offered, recommended } = getAvailableStandards(manifest);
61
59
  const msg = t().availableStandards;
62
- const shown = offered.slice(0, 5).map(s => s.id).join(', ');
63
- return [{
64
- standard: msg.frictionStandard.replace('{count}', offered.length),
65
- type: 'not-installed',
66
- severity: 'LOW',
67
- diff: offered.length > 5 ? `${shown}, …` : shown,
68
- suggestion: msg.frictionSuggestion
69
- }];
60
+ const findings = [];
61
+ if (offered.length > 0) {
62
+ const shown = offered.slice(0, 5).map(s => s.id).join(', ');
63
+ findings.push({
64
+ standard: msg.frictionStandard.replace('{count}', offered.length),
65
+ type: 'not-installed',
66
+ severity: 'LOW',
67
+ diff: offered.length > 5 ? `${shown}, …` : shown,
68
+ suggestion: msg.frictionSuggestion
69
+ });
70
+ }
71
+ // XSPEC-475 R9: the recommended core standards are named, with the command that installs each one.
72
+ if (recommended.length > 0) {
73
+ findings.push({
74
+ standard: msg.frictionRecommended.replace('{count}', recommended.length),
75
+ type: 'not-installed',
76
+ severity: 'LOW',
77
+ diff: recommended.map(s => s.id).join(', '),
78
+ suggestion: recommended.map(s => `uds update --apply --add-standard ${s.id}`).join('; ')
79
+ });
80
+ }
81
+ return findings;
70
82
  }
71
83
 
72
84
  /**
@@ -16,6 +16,8 @@ const TABLE_FIELD = (name) => new RegExp(`^\\|\\s*\\**\\s*(?:${name})\\s*\\**\\s
16
16
  /** ...in a field line: `- **Status**: Archived`, `> **Status**: Stable`, `Status: Draft`. */
17
17
  const LINE_FIELD = (name) => new RegExp(`^[\\s>*-]*\\**\\s*(?:${name})\\s*\\**\\s*[:\uFF1A]\\s*\\**\\s*(.+?)\\s*$`, 'i');
18
18
  const TABLE_SEPARATOR = /^\|[\s:|-]+\|?\s*$/;
19
+ /** Between two fields on one line: a full-width or half-width bar. */
20
+ const FIELD_SEPARATOR = /\s*[\uFF5C|]\s*/;
19
21
 
20
22
  /** First word of a header value, lower-cased (`Approved (2026-01-01)` -> `approved`); text it cannot split stays as written. */
21
23
  function headerWord(value) {
@@ -51,6 +53,15 @@ export function readSddHeader(content) {
51
53
  const row = TABLE_FIELD(name).exec(lines[i]);
52
54
  // A header row of a table (`| Status | Description |`) is followed by a separator row; a field row is not.
53
55
  if (row && !TABLE_SEPARATOR.test(lines[i + 1] || '')) return headerWord(row[1]);
56
+ // XSPEC-475 R8: several fields on one line, separated by a full-width `|` or a half-width `|`
57
+ // (`**規格**: SPEC-002 | **狀態**: Draft(驗收中)`). Each piece is read as a field line of its own. A table row
58
+ // (a line that starts with `|`) was handled above and is never split.
59
+ if (!/^\s*\|/.test(lines[i])) {
60
+ for (const piece of lines[i].split(FIELD_SEPARATOR)) {
61
+ const inPiece = LINE_FIELD(name).exec(piece); // [mutation-anchor:same-line-fields]
62
+ if (inPiece) return headerWord(inPiece[1]);
63
+ }
64
+ }
54
65
  const field = LINE_FIELD(name).exec(lines[i]);
55
66
  if (field) return headerWord(field[1]);
56
67
  }
@@ -4,7 +4,7 @@ import * as yaml from 'js-yaml';
4
4
  import { exec } from 'child_process';
5
5
  import util from 'util';
6
6
  import { pathToFileURL } from 'node:url';
7
- import { readManifest } from './copier.js';
7
+ import { readManifest, getRepoRoot } from './copier.js';
8
8
  import { judgeCommitMessage } from './commit-message-judge.js';
9
9
 
10
10
  const execAsync = util.promisify(exec);
@@ -461,9 +461,10 @@ export class StandardValidator {
461
461
  const judgeName = simulator.judge
462
462
  || (standardConfig?.standard?.id === 'commit-message' && /commitlint/.test(simulator.command || '') ? 'commit-message' : null);
463
463
  if (judgeName === 'commit-message') {
464
- const outcome = judgeCommitMessage(standardConfig, input, { standardsDir: this.standardsDir });
464
+ const outcome = judgeCommitMessage(standardConfig, input, { standardsDir: this.standardsDir, shippedRoot: getRepoRoot() }); // wire:simulate-shipped-root
465
465
  const details = [
466
466
  ...outcome.findings.map(f => `- ${f}`),
467
+ ...outcome.notes.map(n => `Note: ${n}`),
467
468
  `Checked: ${outcome.checked.join('; ')}`,
468
469
  `Not checked: ${outcome.notChecked.join('; ')}`
469
470
  ].join('\n');
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "version": "6.14.0-beta.11",
3
+ "version": "6.14.0-beta.12",
4
4
  "lastUpdated": "2026-05-13",
5
5
  "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
6
6
  "formats": {
@@ -58,14 +58,14 @@
58
58
  "standards": {
59
59
  "name": "universal-dev-standards",
60
60
  "url": "https://github.com/AsiaOstrich/universal-dev-standards",
61
- "version": "6.14.0-beta.11"
61
+ "version": "6.14.0-beta.12"
62
62
  },
63
63
  "skills": {
64
64
  "name": "universal-dev-standards",
65
65
  "url": "https://github.com/AsiaOstrich/universal-dev-standards",
66
66
  "localPath": "skills",
67
67
  "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
68
- "version": "6.14.0-beta.11",
68
+ "version": "6.14.0-beta.12",
69
69
  "note": "Skills are now included in the main repository under skills/"
70
70
  }
71
71
  },
@@ -774,6 +774,7 @@
774
774
  "ai": "ai/standards/turn-completion-integrity.ai.yaml"
775
775
  },
776
776
  "category": "core",
777
+ "recommended": true,
777
778
  "description": "An agent must not end a turn having stated a next action it did not take; enforced at turn end by a Stop hook, with a per-language corpus that runs in CI"
778
779
  },
779
780
  {
@@ -2295,6 +2296,7 @@
2295
2296
  "ai": "ai/standards/pipeline-security-gates.ai.yaml"
2296
2297
  },
2297
2298
  "category": "core",
2299
+ "recommended": true,
2298
2300
  "description": "Security checkpoints embedded in CI pipeline — SAST, DAST, SCA, secrets scan (including the scanner's own output and failure behaviour) with block/warn/log behavior"
2299
2301
  },
2300
2302
  {
@@ -2334,7 +2336,7 @@
2334
2336
  "id": "license-compliance",
2335
2337
  "name": "License Compliance Standards",
2336
2338
  "nameZh": "授權合規標準",
2337
- "version": "6.14.0-beta.11",
2339
+ "version": "6.14.0-beta.12",
2338
2340
  "source": {
2339
2341
  "human": "core/license-compliance.md",
2340
2342
  "ai": "ai/standards/license-compliance.ai.yaml"
@@ -2346,7 +2348,7 @@
2346
2348
  "id": "verification-oracle",
2347
2349
  "name": "Verification Oracle Standards",
2348
2350
  "nameZh": "驗證 Oracle 標準",
2349
- "version": "6.14.0-beta.11",
2351
+ "version": "6.14.0-beta.12",
2350
2352
  "source": {
2351
2353
  "human": "core/verification-oracle.md",
2352
2354
  "ai": "ai/standards/verification-oracle.ai.yaml"
@@ -2358,7 +2360,7 @@
2358
2360
  "id": "model-provenance",
2359
2361
  "name": "Model Provenance Policy Standards",
2360
2362
  "nameZh": "模型來源政策標準",
2361
- "version": "6.14.0-beta.11",
2363
+ "version": "6.14.0-beta.12",
2362
2364
  "source": {
2363
2365
  "human": "core/model-provenance.md",
2364
2366
  "ai": "ai/standards/model-provenance.ai.yaml"
@@ -2370,7 +2372,7 @@
2370
2372
  "id": "resource-cost-boundary",
2371
2373
  "name": "Resource / Cost Boundary Declaration Standards",
2372
2374
  "nameZh": "資源/成本邊界宣告標準",
2373
- "version": "6.14.0-beta.11",
2375
+ "version": "6.14.0-beta.12",
2374
2376
  "source": {
2375
2377
  "human": "core/resource-cost-boundary.md",
2376
2378
  "ai": "ai/standards/resource-cost-boundary.ai.yaml"
@@ -2464,7 +2466,7 @@
2464
2466
  "ai": "ai/standards/secret-management-standards.ai.yaml"
2465
2467
  },
2466
2468
  "category": "core",
2467
- "description": "Three secret source tiers (Vault, Cloud KMS, SOPS), rotation policies by credential type, hardcoded secret prevention, and safe injection patterns"
2469
+ "description": "Three secret source tiers (Vault, Cloud KMS, SOPS), rotation policies by credential type, hardcoded secret prevention (scanner rules PSG-1 to PSG-3 of pipeline-security-gates), and safe injection patterns"
2468
2470
  },
2469
2471
  {
2470
2472
  "id": "prd-standards",