universal-dev-standards 5.10.0 → 5.12.1

package/bundled/core/license-compliance.md

@@ -0,0 +1,118 @@
+# License Compliance Standards
+
+> **Version**: 2.1.0 | **Status**: Active | **Updated**: 2026-05-16
+> **AI-optimized version**: `ai/standards/license-compliance.ai.yaml`
+> **Agent Spec**: ASPEC-001 (cross-project/aspec/ASPEC-001-license-compliance-agent.md)
+
+## Overview
+
+Comprehensive license compliance for AI-augmented development, covering both general OSS practice (Tier 1) and AI-specific rules for AI-generated code (Tier 2).
+
+## Tier 1 — General OSS Compliance Practices
+
+Applies to every project regardless of AI use.
+
+| ID | Rule | Level |
+|----|------|-------|
+| REQ-001 | License classification and allowlist | MUST |
+| REQ-002 | Automated license scanning in CI | MUST |
+| REQ-003 | SBOM generation (CycloneDX 1.5 or SPDX 2.3) | MUST |
+| REQ-004 | License attribution and NOTICES file | MUST |
+| REQ-005 | License violation remediation (5 business days) | MUST |
+| REQ-006 | License review for new technology adoption | SHOULD |
+
+### License Tiers
+
+| Tier | Licenses | Action |
+|------|----------|--------|
+| APPROVED | MIT, Apache 2.0, BSD-2/3-Clause, ISC, CC0 | Auto-approve |
+| REVIEW-REQUIRED | LGPL-2.1/3.0, MPL-2.0, CDDL | Legal review before adoption |
+| PROHIBITED | GPL-2.0/3.0, AGPL-3.0, SSPL-1.0, BUSL-1.1 | Block PR immediately |
+
+## Tier 2 — AI-Specific Rules
+
+Binding on AI Agents that produce code (VibeOps Generator Agent and equivalents).
+
+| ID | Rule | Severity |
+|----|------|----------|
+| LC-001 | SPDX ID lookup required | Blocking |
+| LC-002 | Blocklist auto-block | Blocking |
+| LC-003 | Allowlist auto-approve | Informational |
+| LC-004 | Greylist human review | Review required |
+| LC-005 | SBOM mandatory generation | Blocking |
+| LC-006 | Copyright similarity threshold (≥0.85 block) | Blocking |
+| LC-007 | PII pattern detection | Review required |
+| LC-008 | EU AI Act transparency marker | Blocking |
+| LC-009 | Customer policy ceiling | Informational |
+
+## v2.1.0 Enhancements (XSPEC-193 Phase 2)
+
+### ClearlyDefined API (LC-001)
+
+- Primary license lookup source: `https://api.clearlydefined.io/definitions/{type}/{provider}/{namespace}/{name}/{revision}`
+- Confidence ≥ 0.95 for well-known packages (score.total ≥ 80)
+- 24h TTL LRU cache (cap=500) + negative cache for 404
+- Token bucket: 10 req/s, burst 20
+- Retry strategy: 5xx → exponential backoff × 3 (200ms/1s/3s); 429 → batch fallback
+- DEC-064 cache key isolation: `sha256(client_salt + ':' + purl)`
+
+### AST PII Analysis (LC-007)
+
+- Tree-sitter support: TypeScript, JavaScript, Python
+- Context classification:
+  - `hardcoded_value` → severity upgraded to `critical`
+  - `comment` → severity downgraded to `info`
+  - `schema_field` → annotated, no severity change
+- `// pii:ignore` pragma: suppresses findings on same line
+- Optional fields: `PIIPattern.confidence`, `PIIPattern.ast_context`
+- Graceful fallback to regex when tree-sitter unavailable
+
+### EmbeddingProvider Strategy (LC-006)
+
+- `provider='onnx-minilm'`: ONNX local inference (all-MiniLM-L6-v2)
+- `provider='ollama-bge-m3'`: Ollama local API (localhost:11434)
+- `provider='jaccard'`: Jaccard token similarity (Phase 1 baseline, default)
+- In-memory snippet index (`buildSnippetIndex()`) per-customer (DEC-064 salt)
+- External search: opt-in via `enableExternalSearch=true` (default=false)
+
+## Principles
+
+| ID | Principle |
+|----|-----------|
+| P-1 | SPDX First — all license IDs must be SPDX standard |
+| P-2 | Independent Evaluator — different model class from Generator |
+| P-3 | Evidence-Based Decision — every block carries traceable evidence |
+| P-4 | Transparency by Default — EU AI Act Article 50 markers required |
+| P-5 | Customer Sovereignty — policy customizable within EULA §9 limits |
+
+## Tool Sequence (XSPEC-193 §2)
+
+```
+1. dependency_reader
+2. license_lookup         ← ClearlyDefined API (v2.1.0)
+3. license_blocklist_check
+4. sbom_generator
+5. pii_pattern_detector   ← AST-enhanced (v2.1.0)
+6. copyright_similarity_check ← EmbeddingProvider (v2.1.0)
+7. eu_ai_act_classifier
+8. transparency_marker
+9. block_pr
+10. suggest_alternative
+11. escalate_to_human
+```
+
+## Related Specs
+
+- XSPEC-193 — License Compliance Agent complete spec
+- XSPEC-066 — Wave 3 Compliance Pack (v1.0.0 baseline)
+- DEC-063 — VibeOps legal & compliance strategy
+- DEC-064 — Customer IP isolation (cache salt)
+- ASPEC-001 — License Compliance Agent SPEC (XSPEC-205 §REQ-2 format)
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| v1.0.0 | 2026-04-30 | Initial — REQ-001~006 general OSS practices |
+| v2.0.0 | 2026-05-14 | Added Tier 2 LC-001~009 AI-specific rules |
+| v2.1.0 | 2026-05-16 | ClearlyDefined API + AST PII + EmbeddingProvider + ASPEC-001 ref |

package/bundled/core/llm-output-validation.md

@@ -176,3 +176,6 @@ npx vitest run agents/__tests__/contract.test.ts
 - ISO/IEC 42001:2023 — AI 管理系統
 - [UDS `security-testing.ai.yaml`](./security-testing.md) — SAST + DAST 整合
 - [UDS `adversarial-test.ai.yaml`](./adversarial-test.md) — Prompt injection 紅隊標準
+
+
+**Scope**: universal

package/bundled/core/no-cicd-deployment.md

@@ -203,3 +203,6 @@ status:
 - `deployment-standards.ai.yaml` — 有 CI/CD 平台的部署策略（本文件的補充前提）
 - `health-check-standards.ai.yaml` — /health 端點設計規範
 - `circuit-breaker.ai.yaml` — 斷路器整合（進階場景）
+
+
+**Scope**: universal

package/bundled/core/pipeline-security-gates.md

@@ -107,3 +107,6 @@
 - [pipeline-integration-standards.md](pipeline-integration-standards.md) — CI 管線整合標準
 - [deployment-standards.md](deployment-standards.md) — 部署基礎原則
 - AI 格式：[../ai/standards/pipeline-security-gates.ai.yaml](../ai/standards/pipeline-security-gates.ai.yaml)
+
+
+**Scope**: universal

package/bundled/core/policy-as-code-testing.md

@@ -186,3 +186,6 @@ policies/
 - [UDS `secure-op.ai.yaml`](./secure-op.md) — AI Agent 安全操作六大支柱
 - [UDS `adversarial-test.ai.yaml`](./adversarial-test.md) — 對抗性測試（OWASP LLM01）
 - [UDS `container-security.ai.yaml`](./container-security.md) — 容器安全（OPA Sidecar 部署）
+
+
+**Scope**: universal

package/bundled/core/prompt-regression.md

@@ -70,3 +70,6 @@ The comment is mandatory. PRs that update checksums without explanatory comments
 - [LLM Output Validation](llm-output-validation.md) — schema-level validation
 - [Adversarial Test](adversarial-test.md) — red-team corpus
 - [Testing Standards](testing.md) — overall testing pyramid
+
+
+**Scope**: universal

package/bundled/core/property-based-testing.md

@@ -71,3 +71,6 @@ fc.assert(property, { seed: 1234567890 })
 - [Mutation Testing Standards](mutation-testing.md) — complement to PBT
 - [Testing Standards](testing-standards.md) — overall test pyramid
 - [Adversarial Test Standards](adversarial-test.md) — security-focused fuzzing
+
+
+**Scope**: universal

package/bundled/core/recovery-recipe-registry.md

@@ -67,3 +67,6 @@ escalation:                         # required
 - XSPEC-046: Cross-project specification
 - Depends on: Failure Source Taxonomy (XSPEC-045)
 - Borrowed from: [ultraworkers/claw-code](https://github.com/ultraworkers/claw-code) ROADMAP Phase 3 Recovery Recipes
+
+
+**Scope**: universal

package/bundled/core/release-quality-manifest.md

@@ -191,3 +191,6 @@ Generate a Markdown table alongside the YAML for inclusion in release notes:
 - `supply-chain-attestation.ai.yaml` — SBOM and provenance
 - `testing.ai.yaml` — overall test strategy
 - `deployment-standards.ai.yaml` — release gate integration
+
+
+**Scope**: universal

package/bundled/core/replay-test.md

@@ -84,3 +84,6 @@ describe("Guardian replay fixtures", () => {
 - [Adversarial Test Standards](adversarial-test.md) — red-team corpus
 - [Verification Evidence Standards](verification-evidence.md) — AC traceability
 - [Testing Standards](testing.md) — overall test pyramid
+
+
+**Scope**: universal

package/bundled/core/retry-standards.md

@@ -60,3 +60,6 @@ wait_ms = min(cap_ms, base_ms * 2^attempt) * (0.5 + random() * 0.5)
 - DEC-043: UDS 覆蓋完整性路線圖（驅動來源）
 - Related: `circuit-breaker`, `failure-source-taxonomy`, `timeout-standards`, `recovery-recipe-registry`
 - Industry: Netflix Hystrix retry, Google SRE Book Ch.22, AWS Architecture Blog — exponential backoff and jitter
+
+
+**Scope**: universal

package/bundled/core/rollback-standards.md

@@ -102,3 +102,6 @@
 - [deployment-standards.md](deployment-standards.md) — 部署基礎策略
 - [cd-deployment-strategies.md](cd-deployment-strategies.md) — 部署策略選用矩陣
 - AI 格式：[../ai/standards/rollback-standards.ai.yaml](../ai/standards/rollback-standards.ai.yaml)
+
+
+**Scope**: universal

package/bundled/core/sast-advanced.md

@@ -5,7 +5,7 @@
 **Version**: 1.0.0
 **Last Updated**: 2026-05-05
 **Applicability**: TypeScript / JavaScript projects
-**Scope**: CI/CD security enforcement
+**Scope**: universal
 **References**: [CodeQL documentation](https://codeql.github.com/), [gitleaks](https://github.com/gitleaks/gitleaks), [Biome linter](https://biomejs.dev/)
 
 ---

package/bundled/core/secure-op.md

@@ -312,3 +312,6 @@ P0c 等級 + 外部稽核師可存取的 Audit Chain 匯出功能。
 - `security-testing`：安全測試方法論（SAST、DAST、依賴審計）
 - `audit-trail`：一般 Audit Trail 標準
 - `mock-boundary`：測試中禁止 mock 安全控制
+
+
+**Scope**: universal

package/bundled/core/security-decision.md

@@ -63,3 +63,6 @@ function arbitrate(rules: SecurityDecisionRule[]): SecurityDecision {
 - AI-optimized: [ai/standards/security-decision.ai.yaml](../ai/standards/security-decision.ai.yaml)
 - XSPEC-037: Cross-project specification
 - Borrowed from: [claude-code-book](https://github.com/lintsinghua/claude-code-book) Ch.4 four-stage permission pipeline
+
+
+**Scope**: universal

package/bundled/core/server-ops-security.md

@@ -491,3 +491,6 @@ Guardian OPA Sidecar（XSPEC-146/147）作為 AI Agent 的決策閘道，其所
 - `security-testing.ai.yaml` — SAST、DAST、相依套件審計
 - `secret-management-standards.ai.yaml` — 機密管理與憑證衛生
 - `container-image-standards.ai.yaml` — 容器映像安全基準
+
+
+**Scope**: universal

package/bundled/core/skill-standard-alignment-check.md

@@ -77,3 +77,6 @@ Skill 必有 Standard 作為錨點，Standard 可無 Skill；定期識別孤兒
 - DEC-043: UDS 覆蓋完整性路線圖（XSPEC-063~069 目的之一即清空本標準識別的 orphan 清單）
 - Related: `standard-admission-criteria`, `standard-lifecycle-management`
 - Internal: AsiaOstrich DEC-043 七主題缺口分析（slo/runbook/observability 等 40+ Skill 部分無 Standard 錨點）
+
+
+**Scope**: universal

package/bundled/core/smoke-test.md

@@ -63,3 +63,6 @@ echo "=== PASS ==="
 - [Testing Standards](testing.md) — overall test pyramid
 - [Deployment Standards](deployment-standards.md) — deployment pipeline
 - [Performance Standards](performance-standards.md) — latency SLOs
+
+
+**Scope**: universal

package/bundled/core/standard-admission-criteria.md

@@ -82,3 +82,6 @@
 - DEC-043: UDS 覆蓋完整性路線圖（本標準是 Wave 1 前置條件）
 - Related: `standard-lifecycle-management`, `skill-standard-alignment-check`, `adr-standards`
 - Industry: IETF RFC admission criteria, Python PEP process, W3C Recommendation Track
+
+
+**Scope**: universal

package/bundled/core/standard-lifecycle-management.md

@@ -92,3 +92,6 @@ Deprecated ──(migration done)───→ Archived
 - DEC-043: UDS 覆蓋完整性路線圖（驅動來源）
 - Related: `standard-admission-criteria`, `skill-standard-alignment-check`, `adr-standards`
 - Industry: IETF RFC lifecycle (Proposed → Draft → Internet Standard), Python PEP states, W3C Recommendation Track
+
+
+**Scope**: universal

package/bundled/core/supply-chain-attestation.md

@@ -115,3 +115,6 @@ app-commercial-v1.3.0/
 - [Supply Chain Security Standards](supply-chain-security-standards.md) — dependency audit policies
 - [Container Security Standards](container-security.md) — image hardening
 - [Advanced SAST Standards](sast-advanced.md) — static analysis
+
+
+**Scope**: universal

package/bundled/core/timeout-standards.md

@@ -61,3 +61,6 @@ Downstream DB timeout  =  5120 ms   (6400  × 0.8)
 - DEC-043: UDS 覆蓋完整性路線圖（驅動來源）
 - Related: `circuit-breaker`, `retry-standards`, `failure-source-taxonomy`
 - Industry: gRPC deadline propagation, Envoy timeout budgeting, Google SRE Book Ch.22
+
+
+**Scope**: universal

package/bundled/core/token-budget.md

@@ -56,3 +56,6 @@ Compression operations need output space to succeed. Reserve constants:
 - AI-optimized: [ai/standards/token-budget.ai.yaml](../ai/standards/token-budget.ai.yaml)
 - XSPEC-036: Cross-project specification
 - Borrowed from: [claude-code-book](https://github.com/lintsinghua/claude-code-book) Ch.7 four-zone context management
+
+
+**Scope**: universal

package/bundled/locales/zh-CN/CHANGELOG.md

@@ -1,8 +1,8 @@
 ---
 source: ../../CHANGELOG.md
-source_version: 5.10.0
-translation_version: 5.10.0
-last_synced: 2026-05-13
+source_version: 5.12.1
+translation_version: 5.12.1
+last_synced: 2026-05-19
 status: current
 ---
 
@@ -17,6 +17,45 @@ status: current
 
 ## [Unreleased]
 
+## [5.12.0] - 2026-05-16
+
+### 新增
+- **`docs/user/` 用户文档体系**（XSPEC-211）：新增双轨文档结构，仿照 VibeOps 惯例，包含 8 份文档：
+  - `docs/user/GETTING-STARTED.md` — 5 分钟端到端教程（install → `uds init` → `/sdd` → `/commit`）
+  - `docs/user/SKILLS-INDEX.md` — 自动生成的 54 个 skill 索引，按 Tier（DEC-061）与 Category 分类，含「触发时机速查」表
+  - `docs/user/COMMANDS-INDEX.md` — 自动生成的 48 个 slash command 字母序列表，含 skill 对应
+  - `docs/user/FAQ.md` — 14 题常见问题（安装、skill、SDD、升级、架构）
+  - `docs/user/GLOSSARY.md` — UDS、SDD、ATDD、BDD、TDD、XSPEC、Dual-Layer、Skill Tier、Standard、Activity、Bundle/Source、ADR、AC 等术语定义
+  - `docs/user/TROUBLESHOOTING.md` — 问题→解法指南，整合 `SKILL-FALLBACK-GUIDE.md` 内容
+  - `docs/user/README.md` — 三类受众入口（新手 / 日常用户 / 维护者）+ 文档地图
+  - `docs/user/CHEATSHEET.md` — 从 `docs/` 移入（内容不变）
+- **`scripts/generate-skill-index.ts`** — 从 `uds-manifest.json` + `skills/*/SKILL.md` frontmatter 生成 SKILLS-INDEX.md 与 COMMANDS-INDEX.md。执行：`npm run docs:generate-index`
+- **`scripts/check-skill-index.ts`** — pre-commit 守门；重生成后 diff，不同步则 exit 非零。执行：`npm run docs:check-index`
+- **`scripts/setup-hooks.sh`** — 安装 `.git/hooks/pre-commit`，每次 commit 自动调用 `docs:check-index`
+- **`.github/workflows/docs-check.yml`** — CI job：PR 修改 manifest/SKILL.md/registry 时验证 INDEX 文档已同步
+- **`docs/reference/FEATURE-REFERENCE.md`** — FEATURE-REFERENCE.md 从 `docs/` 迁移至 `docs/reference/`（自动生成，内容不变）
+- **`docs/archive/USER-MANUAL-2026-03-24.md`** — 已废弃 User Manual 的归档备份
+
+### 变更
+- **`package.json`**：新增 `docs:generate-index` 与 `docs:check-index` npm scripts
+- **`scripts/generate-usage-docs.mjs`**：更新英文输出路径（FEATURE-REFERENCE → `docs/reference/`，CHEATSHEET → `docs/user/`）
+- **`skills/README.md`**：新增 banner 指向 `docs/user/SKILLS-INDEX.md` 与 `COMMANDS-INDEX.md`
+- **`README.md`**：Quick Start 段落新增「📚 Documentation」表格，列出 7 份 `docs/user/` 文档直链
+- **`docs/USER-MANUAL.md`**：新增 deprecation banner 指向 `docs/user/README.md`；归档备份保留于 `docs/archive/`
+
+### 移除
+- **`docs/SKILL-FALLBACK-GUIDE.md`**：内容已整合至 `docs/user/TROUBLESHOOTING.md`。非 Claude Code 工具的 fallback 策略与 Skill→Core Standard 对应表保留于「Using UDS Without Claude Code」段落
+
+## [5.11.0] - 2026-05-14
+
+### 新增 / Added
+- **`spec-driven-development`** SPEC Type Agent 变体：`acceptance-criteria-traceability.ai.yaml` 与 SDD 模板新增 `spec-type: feature | agent | infrastructure` 字段，以及 Agent SPEC 五段式模板（能力范围 / 决策边界 / 可观测性 / 失败模式 / 跨 Agent 不变量）。让 Builder/QA/Planner 风格的 SPEC 可独立于 feature SPEC 追踪，并通过新增的 `agent-id` 字段连回特定 Agent。(XSPEC-205)
+- **`reverse-engineering-standards`** 移植清单双向验证：新增路由驱动的发现方法（禁止以 filesystem-glob 为起点）、target→source 双向扫描，以及对"无对应来源产物"的发现的 `[GAP]` 标记协议。搭配 `testing.ai.yaml` 新增 `migration_testing` 区段，要求以 3 步骤 schema parity pattern 并由 CI gate 强制执行。关闭 UDS Issue #96 与 #97。(XSPEC-206)
+
+### 修复 / Fixed
+- **`uds update` 对 schema 3.x manifest 误报"CLAUDE.md.md：无法判断来源"还原失败**（`cli/src/utils/integration-generator.js`、`cli/src/commands/update.js`）：schema 3.x manifest 在 `manifest.integrations` 存的是**文件名**（如 `"CLAUDE.md"`）而非工具名。`integration-generator.js:56` 的 `getToolFileName` fallback 无条件附加 `".md"`，导致 `getToolFilePath("CLAUDE.md")` 返回 `"CLAUDE.md.md"`，被当成丢失文件而无法还原（`getSourcePathFromRelative` 对该合成路径没有 mapping）。Commit `79532b3`（5.10.0）修了反向案例（工具名输入），但漏这个文件名变体。修补：从 `SUPPORTED_AI_TOOLS` 预计算 `KNOWN_TOOL_FILES`，对已知集成文件名或已含已知扩展名（`.md`/`.yaml`/`.yml`/`.json`）的输入短路返回。`integration-generator.test.js` 新增 5 个 regression test。(XSPEC-208 BUG-208-01)
+- **`uds update` / `uds check` 误报"Integration UDS Block Integrity：GEMINI.md/AGENTS.md 丢失"警告**（`cli/src/commands/update.js`、`cli/src/i18n/messages.js`）：`manifest.integrationBlockHashes` 每次安装都累加但从不清理。当 `manifest.aiTools` 缩减（如 `["claude-code","gemini-cli"]` → `["claude-code"]`），GEMINI.md 的 hash 仍残留，`check.js:1491 checkIntegrationBlocksIntegrity` 误报该文件丢失。修补：在 integration 重新生成步骤后，依 `manifest.aiTools`（声明的配置，而非 `results.integrations`，后者在暂时性写入失败时会 over-prune）反推预期文件名集合并移除孤儿 hash。被清理的文件名通过新增 i18n key `prunedOrphanedBlockHashes`（en / zh-TW / zh-CN）回报。`update.test.js` 新增 3 个 regression test。在 machine-setup `uds update` 5.1.0-beta.4 → 5.10.0 触发；于 5.10.0 → 5.11.0 验证修复。(XSPEC-208 BUG-208-02)
+
 ## [5.10.0] - 2026-05-13
 
 ### 新增

package/bundled/locales/zh-CN/CLAUDE.md

@@ -14,7 +14,7 @@ status: current
 
 Universal Development Standards 是一个语言无关、框架无关的文件化标准框架。它提供：
 
-- **核心规范** (`core/`)：71 个基础开发标准
+- **核心规范** (`core/`)：125 个基础开发标准
 - **AI 技能** (`skills/`)：用于 AI 辅助开发的 Claude Code 技能
 - **CLI 工具** (`cli/`)：用于采用标准的 Node.js CLI
 - **整合** (`integrations/`)：各种 AI 工具的配置

package/bundled/locales/zh-CN/README.md

@@ -14,7 +14,7 @@ status: current
 
 > **语言**: [English](../../README.md) | [繁體中文](../zh-TW/README.md) | 简体中文
 
-**版本**: 5.10.0 | **发布日期**: 2026-04-13 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
+**版本**: 5.12.1 | **发布日期**: 2026-05-14 | **授权**: [双重授权](../../LICENSE) (CC BY 4.0 + MIT)
 
 语言无关、框架无关的软件项目文档标准。通过 AI 原生工作流，确保不同技术栈之间的一致性、质量和可维护性。
 
@@ -63,8 +63,8 @@ npx universal-dev-standards init
 <!-- UDS_STATS_TABLE_START -->
 | 类别 | 数量 | 说明 |
 |----------|-------|-------------|
-| **核心标准** | 78 | 通用开发准则 |
-| **AI Skills** | 48 | 互动式技能 |
+| **核心标准** | 125 | 通用开发准则 |
+| **AI Skills** | 54 | 互动式技能 |
 | **斜线命令** | 48 | 快速操作 |
 | **CLI 命令** | 6 | list, init, configure, check, update, skills |
 <!-- UDS_STATS_TABLE_END -->

package/bundled/locales/zh-CN/SECURITY.md

@@ -13,8 +13,7 @@ status: current
 <!-- UDS_SUPPORTED_VERSIONS_START -->
 | 版本 | 支持状态 |
 |------|--------|
-| 5.1.0-beta.5 | ✅ 预发布版本 |
-| 5.0.0 | ✅ 最新正式版 |
+| 5.11.0 | ✅ 最新正式版 |
 | < 5.0.0 | ❌ 已终止支持 |
 <!-- UDS_SUPPORTED_VERSIONS_END -->