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
package/bin/uds.js CHANGED
@@ -233,7 +233,8 @@ program
233
233
  .option('--apply', 'Apply exactly the plan --plan prints (plain `uds update` does not); with --skills/--commands it does the reconciliation AND that scope, not only the scope')
234
234
  .option('--force', 'Force update all files, ignoring hash comparison')
235
235
  .option('--prune', 'Delete .standards/ files UDS wrote but no longer ships (listed without this flag; never touches files UDS did not write)')
236
- .option('--rollback', 'Rollback to the most recent backup')
236
+ .option('--rollback', 'Rollback to the most recent backup (with the series of updates that follow from it)')
237
+ .option('--from <backup>', 'With --rollback: restore this one backup instead of the most recent series (the id --rollback prints, or its folder name); use it for a backup an older UDS made')
237
238
  .option('--add-standard <id>', 'With --plan or --apply: also install this standard UDS ships and the project lacks, and record it in the manifest (repeatable; `uds update --plan` lists what is available)', (value, previous) => [...previous, value], [])
238
239
  .option('--claude-target <target>', 'Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall')
239
240
  .option('--locale <locale>', 'Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env')
@@ -308,11 +309,17 @@ program
308
309
  console.error(result.error);
309
310
  process.exit(1);
310
311
  }
312
+ // What was left out goes to stderr in a dry run, so stdout stays the JSON it has always been.
313
+ const note = result.dryRun ? console.error : console.log;
311
314
  if (result.dryRun) {
312
315
  console.log(JSON.stringify(result.config, null, 2));
313
316
  } else {
314
317
  console.log(`Compiled ${result.compiledCount} enforcement standard(s) for ${options.target}`);
315
318
  }
319
+ for (const s of result.skipped || []) note(` Skipped ${s.id}: ${s.why}`);
320
+ if ((result.skipped || []).length > 0) {
321
+ note(' Install the hook scripts with \'uds update --with-hooks\' (or \'uds init --with-hooks\'), then compile again.');
322
+ }
316
323
  });
317
324
 
318
325
  program
@@ -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) |
@@ -23,30 +23,73 @@
23
23
  * @see docs/specs/SPEC-HOOKS-001-core-standard-hooks.md (REQ-1)
24
24
  */
25
25
 
26
- const VALID_TYPES = [
27
- 'feat', 'fix', 'docs', 'chore', 'test',
28
- 'refactor', 'style', 'perf', 'ci', 'build', 'revert',
26
+ import { existsSync, readdirSync, readFileSync } from 'node:fs';
27
+ import { join } from 'node:path';
28
+
29
+ /**
30
+ * Used only when the project has no commit-message option file: the Conventional Commits set. Same list `uds simulate
31
+ * -s commit-message` falls back to (FALLBACK_TYPES in cli/src/utils/commit-message-judge.js).
32
+ */
33
+ const FALLBACK_TYPES = [
34
+ 'feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert',
29
35
  ];
30
36
 
31
- const COMMIT_PATTERN = new RegExp(
32
- `^(${VALID_TYPES.join('|')})(\\(.+\\))?:\\s.+`
33
- );
37
+ /**
38
+ * The commit types the project allows: those listed by the commit-message option files installed in
39
+ * `.standards/options/` (a file whose `meta.parent` is `commit-message`), or the fallback set when there are none.
40
+ *
41
+ * XSPEC-482 R12: this was a fixed list that lacked `security`, so `uds simulate` (which reads these same files) passed
42
+ * `security(auth): rotate keys` and this hook refused it. The two now read one source. The hook has no YAML parser
43
+ * to lean on (it runs in the adopter's project with no dependencies), so it reads the two things it needs line by line:
44
+ * the `parent:` of the `meta:` block and the `- type:` entries under `types:`.
45
+ *
46
+ * @param {string} [root] - the project root; defaults to $CLAUDE_PROJECT_DIR or the working directory
47
+ * @returns {string[]}
48
+ */
49
+ export function allowedTypes(root = process.env.CLAUDE_PROJECT_DIR || process.cwd()) {
50
+ const found = new Set();
51
+ const optionsDir = join(root, '.standards', 'options');
52
+ for (const dir of [optionsDir, join(optionsDir, 'commit-message')]) {
53
+ if (!existsSync(dir)) continue;
54
+ let names = [];
55
+ try { names = readdirSync(dir).filter((n) => n.endsWith('.ai.yaml')); } catch { continue; }
56
+ for (const name of names) {
57
+ let text = '';
58
+ try { text = readFileSync(join(dir, name), 'utf-8').replace(/\r\n/g, '\n'); } catch { continue; }
59
+ if (!/^\s+parent:\s*["']?commit-message["']?\s*$/m.test(text)) continue;
60
+ const lines = text.split('\n');
61
+ const start = lines.findIndex((l) => /^types:\s*$/.test(l));
62
+ if (start === -1) continue;
63
+ for (let i = start + 1; i < lines.length; i++) {
64
+ if (/^\S/.test(lines[i]) && !lines[i].startsWith('#')) break; // next top-level key
65
+ const m = /^\s*-\s+type:\s*["']?([^"'#\s][^"'#]*?)["']?\s*(?:#.*)?$/.exec(lines[i]);
66
+ if (m) found.add(m[1]);
67
+ }
68
+ }
69
+ }
70
+ return found.size > 0 ? [...found] : FALLBACK_TYPES;
71
+ }
72
+
73
+ const escapeRe = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
34
74
 
35
75
  /**
36
76
  * Validate a commit message against Conventional Commits format.
37
77
  * @param {string} msg - The commit message to validate
78
+ * @param {string[]} [types] - the allowed types (default: the project's, see allowedTypes)
38
79
  * @returns {boolean} true if valid
39
80
  */
40
- export function validateCommitMessage(msg) {
81
+ export function validateCommitMessage(msg, types = allowedTypes()) {
41
82
  if (!msg || typeof msg !== 'string') return false;
42
- return COMMIT_PATTERN.test(msg.trim());
83
+ // `type(scope)!: subject`: scope and the breaking-change mark are optional, as in `uds simulate`.
84
+ const pattern = new RegExp(`^(${types.map(escapeRe).join('|')})(\\(.+\\))?!?:\\s.+`, 'u');
85
+ return pattern.test(msg.trim());
43
86
  }
44
87
 
45
88
  // CLI mode.
46
89
  function complain(msg) {
47
90
  console.error(`❌ Invalid commit message format: "${msg}"`);
48
91
  console.error(` Expected: <type>(<scope>): <subject>`);
49
- console.error(` Valid types: ${VALID_TYPES.join(', ')}`);
92
+ console.error(` Valid types: ${allowedTypes().join(', ')}`);
50
93
  }
51
94
 
52
95
  /**
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../CHANGELOG.md
3
- source_version: 6.14.0-beta.11
4
- translation_version: 6.14.0-beta.11
5
- last_synced: 2026-10-12
3
+ source_version: 6.14.0-beta.13
4
+ translation_version: 6.14.0-beta.13
5
+ last_synced: 2026-10-13
6
6
  status: current
7
7
  ---
8
8
 
@@ -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.13 (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.13 | ✅ 预发布版本 |
18
18
  | 6.13.1 | ✅ 最新正式版 |
19
19
  | < 6.0.0 | ❌ 已终止支持 |
20
20
  <!-- UDS_SUPPORTED_VERSIONS_END -->
@@ -1,6 +1,6 @@
1
1
  # UDS 速查表
2
2
 
3
- > Quick reference for all UDS features | Last updated: 2026-10-12
3
+ > Quick reference for all UDS features | Last updated: 2026-10-13
4
4
 
5
5
  **Language**: [English](../../../docs/user/CHEATSHEET.md) | [繁體中文](../../zh-TW/docs/CHEATSHEET.md) | 简体中文
6
6
 
@@ -1,7 +1,7 @@
1
1
  # UDS 功能参考手册
2
2
 
3
3
  > Universal Development Standards - 完整功能文档
4
- > Auto-generated | Last updated: 2026-10-12
4
+ > Auto-generated | Last updated: 2026-10-13
5
5
 
6
6
  **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | [繁體中文](../../zh-TW/docs/FEATURE-REFERENCE.md) | 简体中文
7
7
 
@@ -155,7 +155,8 @@
155
155
  | `--apply` | Apply exactly the plan --plan prints (plain `uds update` does not); with --skills/--commands it does the reconciliation AND that scope, not only the scope |
156
156
  | `--force` | Force update all files, ignoring hash comparison |
157
157
  | `--prune` | Delete .standards/ files UDS wrote but no longer ships (listed without this flag; never touches files UDS did not write) |
158
- | `--rollback` | Rollback to the most recent backup |
158
+ | `--rollback` | Rollback to the most recent backup (with the series of updates that follow from it) |
159
+ | `--from` | With --rollback: restore this one backup instead of the most recent series (the id --rollback prints, or its folder name); use it for a backup an older UDS made |
159
160
  | `--add-standard` | With --plan or --apply: also install this standard UDS ships and the project lacks, and record it in the manifest (repeatable; `uds update --plan` lists what is available) |
160
161
  | `--claude-target` | Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall |
161
162
  | `--locale` | Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env |
@@ -557,7 +558,7 @@
557
558
  | `runbook` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
558
559
  | `sast-advanced` | 1.0.0 | This standard defines Advanced Static Application Security Testing (SAST) practi |
559
560
  | `schema-evolution` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
560
- | `secret-management-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
561
+ | `secret-management-standards` | 1.1.0 | **Status**: Active | **Updated**: 2026-10-12 | |
561
562
  | `secure-op` | - | |
562
563
  | `security-decision` | - | |
563
564
  | `security-standards` | 1.1.0 | This standard defines comprehensive security guidelines for software development |
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../CHANGELOG.md
3
- source_version: 6.14.0-beta.11
4
- translation_version: 6.14.0-beta.11
5
- last_synced: 2026-10-12
3
+ source_version: 6.14.0-beta.13
4
+ translation_version: 6.14.0-beta.13
5
+ last_synced: 2026-10-13
6
6
  status: current
7
7
  ---
8
8
 
@@ -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.13 (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.13 | ✅ 預發布版本 |
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) |
@@ -1,6 +1,6 @@
1
1
  # UDS 速查表
2
2
 
3
- > Quick reference for all UDS features | Last updated: 2026-10-12
3
+ > Quick reference for all UDS features | Last updated: 2026-10-13
4
4
 
5
5
  **Language**: [English](../../../docs/user/CHEATSHEET.md) | 繁體中文 | [简体中文](../../zh-CN/docs/CHEATSHEET.md)
6
6
 
@@ -1,7 +1,7 @@
1
1
  # UDS 功能參考手冊
2
2
 
3
3
  > Universal Development Standards - 完整功能文件
4
- > Auto-generated | Last updated: 2026-10-12
4
+ > Auto-generated | Last updated: 2026-10-13
5
5
 
6
6
  **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | 繁體中文 | [简体中文](../../zh-CN/docs/FEATURE-REFERENCE.md)
7
7
 
@@ -155,7 +155,8 @@
155
155
  | `--apply` | Apply exactly the plan --plan prints (plain `uds update` does not); with --skills/--commands it does the reconciliation AND that scope, not only the scope |
156
156
  | `--force` | Force update all files, ignoring hash comparison |
157
157
  | `--prune` | Delete .standards/ files UDS wrote but no longer ships (listed without this flag; never touches files UDS did not write) |
158
- | `--rollback` | Rollback to the most recent backup |
158
+ | `--rollback` | Rollback to the most recent backup (with the series of updates that follow from it) |
159
+ | `--from` | With --rollback: restore this one backup instead of the most recent series (the id --rollback prints, or its folder name); use it for a backup an older UDS made |
159
160
  | `--add-standard` | With --plan or --apply: also install this standard UDS ships and the project lacks, and record it in the manifest (repeatable; `uds update --plan` lists what is available) |
160
161
  | `--claude-target` | Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall |
161
162
  | `--locale` | Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env |
@@ -557,7 +558,7 @@
557
558
  | `runbook` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
558
559
  | `sast-advanced` | 1.0.0 | This standard defines Advanced Static Application Security Testing (SAST) practi |
559
560
  | `schema-evolution` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
560
- | `secret-management-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
561
+ | `secret-management-standards` | 1.1.0 | **Status**: Active | **Updated**: 2026-10-12 | |
561
562
  | `secure-op` | - | |
562
563
  | `security-decision` | - | |
563
564
  | `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.13",
4
4
  "description": "CLI tool for adopting Universal Development Standards",
5
5
  "keywords": [
6
6
  "documentation",
@@ -12,7 +12,7 @@
12
12
  */
13
13
 
14
14
  import chalk from 'chalk';
15
- import { checkbox, input } from '@inquirer/prompts';
15
+ import { checkbox, input, confirm } from '@inquirer/prompts';
16
16
  import { createRequire } from 'node:module';
17
17
  import { existsSync, readFileSync } from 'node:fs';
18
18
  import { resolve as resolvePath } from 'node:path';
@@ -465,6 +465,33 @@ async function handleReport(auditResult, options, msg) {
465
465
 
466
466
  const issue = formatIssueContent(filteredResult, userComments);
467
467
 
468
+ // XSPEC-482 R14g: what is about to be sent is shown in full, and sent only after a yes. The interactive path used to go
469
+ // from "your comments" straight to a public issue under the user's GitHub account, so the person never saw the text
470
+ // they were sending. `--yes` (CI, scripts) stays as it was, and a dry run already prints the same text.
471
+ if (!isDryRun && !submitAll) {
472
+ console.log();
473
+ console.log(chalk.bold(msg.reviewBeforeSend || 'This is the report that will be sent:'));
474
+ console.log(chalk.gray('─'.repeat(40)));
475
+ console.log(chalk.cyan(`Title: ${issue.title}`));
476
+ console.log(chalk.cyan(`Labels: ${issue.labels.join(', ')}`));
477
+ console.log(chalk.gray('─'.repeat(40)));
478
+ console.log(issue.body);
479
+ console.log(chalk.gray('─'.repeat(40)));
480
+ let send = false;
481
+ try {
482
+ send = await confirm({
483
+ message: msg.confirmSend || `Send this report as a public issue to ${REPO}?`, // wire:audit-report-confirms
484
+ default: false
485
+ });
486
+ } catch (err) {
487
+ if (!(err && err.name === 'ExitPromptError')) throw err;
488
+ }
489
+ if (!send) {
490
+ console.log(chalk.yellow(msg.notSent || 'Not sent. Nothing was submitted.'));
491
+ return;
492
+ }
493
+ }
494
+
468
495
  if (isDryRun) {
469
496
  console.log();
470
497
  console.log(chalk.bold(msg.dryRunNotice || 'Dry run — no issue created'));
@@ -315,6 +315,37 @@ function displayAdoptionStatus(manifest, msg, common, repoInfo, standardsUpdate)
315
315
  }
316
316
  }
317
317
 
318
+ /**
319
+ * `uds check --json` (without --standard / --i18n): run the whole check with its text held back, then print one JSON
320
+ * document. Held back means console output and anything written to stdout while it runs (a spinner, a warning from a
321
+ * helper); what the check decides is read from the report the main body fills in. The exit code is the one the text mode
322
+ * would give (`--ci` and a non-compliant project: 1).
323
+ * @param {Object} options
324
+ */
325
+ async function checkAsJson(options) {
326
+ const report = { initialized: null, compliant: null };
327
+ const realWrite = process.stdout.write.bind(process.stdout);
328
+ const quiet = () => true;
329
+ const saved = { log: console.log, info: console.info, warn: console.warn };
330
+ process.stdout.write = quiet;
331
+ console.log = console.info = console.warn = () => {};
332
+ try {
333
+ await checkCommand({ ...options, _report: report });
334
+ } finally {
335
+ process.stdout.write = realWrite;
336
+ console.log = saved.log;
337
+ console.info = saved.info;
338
+ console.warn = saved.warn;
339
+ }
340
+ const completed = report.compliant !== null;
341
+ console.log(JSON.stringify({
342
+ success: report.compliant === true,
343
+ initialized: report.initialized,
344
+ completed,
345
+ ...report
346
+ }, null, 2));
347
+ }
348
+
318
349
  /**
319
350
  * Check command - verify adoption status
320
351
  * @param {Object} options - Command options
@@ -376,9 +407,20 @@ export async function checkCommand(options = {}) {
376
407
  return;
377
408
  }
378
409
 
410
+ // XSPEC-482 R9: `--json` is documented as "Output result in JSON format" and used to be honoured only together with
411
+ // `--standard` / `--i18n`; on its own it printed the human text. The checks below run unchanged with their text held
412
+ // back, and what they found is printed as one JSON document.
413
+ if (options.json && !options._report) {
414
+ await checkAsJson(options); // wire:check-json-prints-json
415
+ return;
416
+ }
417
+
379
418
  // Phase 0: Initialization
380
419
  const context = initializeCheckContext(projectPath);
381
- if (!context) return;
420
+ if (!context) {
421
+ if (options._report) options._report.initialized = false;
422
+ return;
423
+ }
382
424
 
383
425
  const { manifest, msg, common, repoInfo } = context;
384
426
 
@@ -389,7 +431,10 @@ export async function checkCommand(options = {}) {
389
431
  // XSPEC-342 R1:先問 npm 最新,判斷「已裝標準」是否落後(離線則跳過,不誤用 CLI bundled 版本)。
390
432
  // fetchLatestVersion 有 60s 模組級快取,故此處與下方 checkCliVersion 共兩次呼叫只打一次網路。
391
433
  let standardsUpdate = null;
392
- if (!options.offline) {
434
+ // XSPEC-482 R14e: UDS_NO_UPDATE_CHECK=1 is the documented switch for "do not ask the npm registry"; `check` asked
435
+ // anyway (and wrote ~/.uds/update-check.json) unless --offline was also given. The variable now counts as --offline here.
436
+ const offline = options.offline || process.env.UDS_NO_UPDATE_CHECK === '1'; // wire:check-honours-no-update-check
437
+ if (!offline) {
393
438
  standardsUpdate = await checkForUpdates(manifest.upstream.version, {
394
439
  checkBeta: manifest.upstream.version.includes('-')
395
440
  });
@@ -399,7 +444,7 @@ export async function checkCommand(options = {}) {
399
444
  displayAdoptionStatus(manifest, msg, common, repoInfo, standardsUpdate);
400
445
 
401
446
  // Check for CLI updates from npm registry (unless --offline)
402
- if (!options.offline) {
447
+ if (!offline) {
403
448
  await checkCliVersion(repoInfo.standards.version);
404
449
  }
405
450
 
@@ -592,6 +637,30 @@ export async function checkCommand(options = {}) {
592
637
  integrationBlockStatus.missing.length === 0 &&
593
638
  integrationBlockStatus.noMarkers.length === 0 &&
594
639
  integrationBlockStatus.ambiguous.length === 0;
640
+ if (options._report) {
641
+ Object.assign(options._report, {
642
+ initialized: true,
643
+ compliant: allGood,
644
+ version: manifest.upstream?.version ?? null,
645
+ installed: manifest.upstream?.installed ?? null,
646
+ files: {
647
+ unchanged: fileStatus.unchanged.length,
648
+ modified: fileStatus.modified,
649
+ missing: fileStatus.missing,
650
+ retired: fileStatus.retired || []
651
+ },
652
+ skillIssues: skillIssues.length,
653
+ commandIssues: commandIssues.length,
654
+ integrationBlocks: {
655
+ modified: integrationBlockStatus.modified,
656
+ missing: integrationBlockStatus.missing,
657
+ noMarkers: integrationBlockStatus.noMarkers,
658
+ ambiguous: integrationBlockStatus.ambiguous
659
+ },
660
+ testChangeBlocked: !!testChange.blocked,
661
+ testGatesBlocked: !!testGates.blocked
662
+ });
663
+ }
595
664
  if (allGood) {
596
665
  console.log(chalk.green(msg.projectCompliant));
597
666
  } else {
@@ -12,6 +12,7 @@ import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from
12
12
  import { join } from 'path';
13
13
  import { load } from 'js-yaml';
14
14
  import { ClaudeCodeCompiler } from '../compilers/claude-code-compiler.js';
15
+ import { mergeHookArray, normalizeMatcher } from '../installers/hooks-installer.js';
15
16
 
16
17
  const COMPILERS = {
17
18
  'claude-code': ClaudeCodeCompiler,
@@ -37,6 +38,17 @@ function parseStandard(filePath) {
37
38
  }
38
39
  }
39
40
 
41
+ /**
42
+ * An entry an earlier `uds compile` wrote with an object matcher (`{ "tool": "Bash" }`) is brought to the string form.
43
+ * Only entries that run a UDS hook script (`node scripts/hooks/...`) are touched; any other entry is returned as it is.
44
+ */
45
+ function repairUdsMatcher(entry) {
46
+ const command = entry && entry.hooks && entry.hooks[0] && entry.hooks[0].command;
47
+ if (typeof command !== 'string' || !command.startsWith('node scripts/hooks/')) return entry;
48
+ if (typeof entry.matcher === 'string' || entry.matcher === undefined) return entry;
49
+ return { ...entry, matcher: normalizeMatcher(entry.matcher) };
50
+ }
51
+
40
52
  /**
41
53
  * Compile enforcement standards into target-specific hook configurations.
42
54
  *
@@ -72,10 +84,22 @@ export function compileStandards(projectPath, options = {}) {
72
84
  .map((f) => parseStandard(join(standardsDir, f)))
73
85
  .filter(Boolean);
74
86
 
87
+ // Only a standard whose hook script is really in the project is compiled. A settings.json entry for a script that
88
+ // is not there makes the tool fail on every call of that event (XSPEC-482 R4c); `uds init --with-hooks` /
89
+ // `uds update --with-hooks` skip such a standard and say so, and so does this.
90
+ const skipped = [];
91
+ const present = standards.filter((s) => {
92
+ if (s.enforcement == null) return true;
93
+ const script = s.enforcement.hook_script;
94
+ if (typeof script === 'string' && script && existsSync(join(projectPath, script))) return true; // wire:compile-skips-missing-script
95
+ skipped.push({ id: s.id || s._file, why: `hook script not found: ${script ?? '(none declared)'}` });
96
+ return false;
97
+ });
98
+
75
99
  // Compile
76
100
  const compiler = new CompilerClass();
77
- const config = compiler.compile(standards);
78
- const compiledCount = compiler.filterEnforceable(standards).length;
101
+ const config = compiler.compile(present);
102
+ const compiledCount = compiler.filterEnforceable(present).length;
79
103
 
80
104
  // Write output (unless dry-run)
81
105
  if (!options.dryRun && compiledCount > 0) {
@@ -96,8 +120,16 @@ export function compileStandards(projectPath, options = {}) {
96
120
  }
97
121
  }
98
122
 
99
- // Merge hooks (replace UDS-compiled hooks entirely)
100
- settings.hooks = { ...(settings.hooks || {}), ...config.hooks };
123
+ // Merge hooks the way `uds update --with-hooks` does (XSPEC-482 R4a): the project's own entries, on the same event
124
+ // or not, stay exactly as they are, and an entry UDS already wrote is not written twice. This used to replace the
125
+ // whole array of every event the standards touched, which deleted a user's own hook on that event.
126
+ settings.hooks = settings.hooks || {};
127
+ for (const [event, entries] of Object.entries(settings.hooks)) {
128
+ settings.hooks[event] = (entries || []).map(repairUdsMatcher);
129
+ }
130
+ for (const [event, incoming] of Object.entries(config.hooks)) {
131
+ settings.hooks[event] = mergeHookArray(settings.hooks[event] || [], incoming); // wire:compile-merges-hooks
132
+ }
101
133
  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
102
134
  }
103
135
 
@@ -105,6 +137,7 @@ export function compileStandards(projectPath, options = {}) {
105
137
  success: true,
106
138
  config,
107
139
  compiledCount,
140
+ skipped,
108
141
  dryRun: !!options.dryRun,
109
142
  };
110
143
  }