universal-dev-standards 5.0.0-rc.8 → 5.0.0

package/bundled/core/workflow-enforcement.md

@@ -0,0 +1,132 @@
+# Workflow Enforcement Standards
+
+**Applicability**: All software projects using structured development methodologies
+**Scope**: universal
+
+## Overview
+
+This standard defines machine-enforceable workflow gates that prevent phase skipping in development methodologies (SDD, TDD, BDD). Instead of relying on developer discipline alone, workflow gates provide automated checks at phase transitions.
+
+## Core Principle
+
+> **Guide, don't just block.** When a prerequisite fails, always provide actionable guidance: what is missing, why it matters, and how to fix it.
+
+## Enforcement Modes
+
+Projects can configure enforcement behavior via `.uds/config.yaml`:
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `enforce` | Block phase transition + show guidance | Teams committed to process discipline |
+| `suggest` | Show warning + allow override | Teams adopting gradually |
+| `off` | No enforcement checks | Opt-out |
+
+**Default**: `enforce`
+
+```yaml
+# .uds/config.yaml
+workflow:
+  enforcement_mode: enforce  # enforce | suggest | off
+```
+
+## Phase Gate Architecture
+
+### How It Works
+
+1. User invokes a workflow command (e.g., `/sdd implement`)
+2. AI assistant checks prerequisites for that phase
+3. If prerequisites pass → proceed normally
+4. If prerequisites fail:
+   - **enforce mode**: Stop, explain, guide to correct phase
+   - **suggest mode**: Warn, allow override
+   - **off mode**: Skip checks entirely
+
+### Gate Types
+
+| Gate Type | Blocking | Description |
+|-----------|----------|-------------|
+| **Hard Gate** | Yes | Must pass to proceed (e.g., spec must be Approved before implement) |
+| **Soft Gate** | No | Advisory warning (e.g., suggest spec reference in commit) |
+
+## SDD Phase Gates
+
+```
+discuss → create → review → approve → implement → verify
+```
+
+| Phase | Prerequisites |
+|-------|--------------|
+| discuss | None (entry point) |
+| create | Check for orphan specs (soft) |
+| review | Spec exists with status = Draft |
+| approve | Spec exists with status = Review, all comments addressed |
+| implement | Spec exists with status = Approved |
+| verify | Implementation exists, all ACs have code + tests |
+
+## TDD Phase Gates
+
+```
+RED → GREEN → REFACTOR → (repeat)
+```
+
+| Phase | Prerequisites |
+|-------|--------------|
+| RED | Feature/behavior clearly defined |
+| GREEN | At least one failing test exists (not error, but assertion failure) |
+| REFACTOR | All tests passing |
+
+**Critical Enforcement**: The AI MUST NOT write implementation code before a failing test exists. This is the fundamental TDD contract.
+
+## BDD Phase Gates
+
+```
+DISCOVERY → FORMULATION → AUTOMATION → LIVING DOCS
+```
+
+| Phase | Prerequisites |
+|-------|--------------|
+| DISCOVERY | Behavior/feature identified |
+| FORMULATION | Concrete examples from discovery exist |
+| AUTOMATION | `.feature` file with Gherkin scenarios exists |
+| LIVING DOCS | Step definitions implemented, all scenarios passing |
+
+## Commit Gates
+
+| Check | Type | Trigger |
+|-------|------|---------|
+| Staged changes exist | Hard | All commits |
+| No merge conflicts | Hard | All commits |
+| Tests pass | Hard | feat/fix commits |
+| Spec reference | Soft | feat/fix commits with active specs |
+
+## Implementation Notes
+
+### For AI Assistants
+
+AI assistants should:
+1. Check gates **before** executing any workflow phase
+2. Use the enforcement mode from project config
+3. Provide clear, actionable guidance when gates fail
+4. Check for resumable workflow state before starting fresh
+5. Track phase transitions in `.workflow-state/`
+
+### For CLI Tools
+
+CLI tools can integrate gates via:
+1. `WorkflowGate` module — validates phase transitions
+2. Pre-commit hooks — warns on workflow compliance
+3. `uds check` — reports workflow state
+
+### For Git Hooks
+
+Git-level enforcement should be **warning-only** (non-blocking) to avoid frustrating developers. The AI layer handles blocking enforcement since it can explain and guide.
+
+## Relationship to Other Standards
+
+| Standard | Relationship |
+|----------|-------------|
+| [Workflow State Protocol](workflow-state-protocol.md) | Gates check state files managed by this protocol |
+| [Spec-Driven Development](spec-driven-development.md) | SDD phase gates enforce SDD workflow |
+| [Testing Standards](testing-standards.md) | TDD/BDD gates enforce testing methodology |
+| [Commit Message Guide](commit-message-guide.md) | Commit gates enforce spec traceability |
+| [Check-in Standards](checkin-standards.md) | Pre-commit gates complement check-in rules |

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

@@ -14,7 +14,7 @@ status: current
 
 Universal Development Standards 是一个语言无关、框架无关的文件化标准框架。它提供：
 
-- **核心规范** (`core/`)：36 个基础开发标准
+- **核心规范** (`core/`)：49 个基础开发标准
 - **AI 技能** (`skills/`)：用于 AI 辅助开发的 Claude Code 技能
 - **CLI 工具** (`cli/`)：用于采用标准的 Node.js CLI
 - **整合** (`integrations/`)：各种 AI 工具的配置
@@ -200,7 +200,7 @@ node cli\bin\uds.js init --help
 
 ```
 universal-dev-standards/
-├── core/                  # 核心规范（36 个档案）
+├── core/                  # 核心规范（49 个档案）
 ├── skills/                # AI 工具技能
 │   └── claude-code/       # Claude Code 技能（26 个技能）
 ├── cli/                   # Node.js CLI 工具

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

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

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

@@ -0,0 +1,92 @@
+# 安全政策
+
+## 支持的版本
+
+<!-- UDS_SUPPORTED_VERSIONS_START -->
+| 版本 | 支持状态 |
+|------|--------|
+| 5.0.0 | ✅ 最新正式版 |
+| < 5.0.0 | ❌ 已终止支持 |
+<!-- UDS_SUPPORTED_VERSIONS_END -->
+
+> **说明**：仅最新正式版与当前预发布分支会收到安全更新。
+
+---
+
+## 报告漏洞
+
+### 如何报告
+
+**请勿**以公开 GitHub issue 报告安全漏洞。
+
+请通过以下渠道报告：
+
+1. **GitHub Security Advisories**（推荐）
+   - 前往 [Security Advisories](https://github.com/AsiaOstrich/universal-dev-standards/security/advisories/new)
+   - 这能确保报告是私密且可追踪的
+
+2. **GitHub 私密漏洞报告**
+   - 前往 [报告漏洞](https://github.com/AsiaOstrich/universal-dev-standards/security)
+   - 按照引导流程报告
+
+### 报告内容
+
+请包含以下信息：
+
+- **描述**：清楚说明漏洞内容
+- **重现步骤**：详细的重现步骤
+- **影响范围**：攻击者可达成的影响
+- **受影响版本**：哪些版本受影响
+- **建议修复方式**：如果您有建议（选填）
+
+### 响应时间
+
+| 动作 | 时间 |
+|------|------|
+| 确认收到 | 48 小时内 |
+| 初步评估 | 7 天内 |
+| 修复发布（严重） | 14 天内 |
+| 修复发布（非严重） | 下次排程发布 |
+
+---
+
+## 安全范畴
+
+### 在范畴内
+
+| 组件 | 说明 |
+|------|------|
+| CLI 工具 (`cli/`) | 命令注入、路径穿越、依赖漏洞 |
+| 标准内容 (`core/`) | 可能导致不安全实现的指引 |
+| GitHub Actions (`.github/workflows/`) | 工作流程注入、机密泄漏 |
+
+### 不在范畴内
+
+- 第三方依赖的漏洞（请报告给上游维护者）
+- 采用 UDS 标准的用户项目中的问题
+- 社交工程攻击
+
+---
+
+## 披露政策
+
+我们遵循**协调披露**原则：
+
+1. 报告者私下提交漏洞
+2. 我们确认并评估
+3. 我们开发并测试修复
+4. 我们发布修复
+5. 我们公开披露漏洞（附上报告者致谢）
+
+除非报告者希望匿名，否则我们会在发布说明中致谢。
+
+---
+
+## 用户安全建议
+
+在您的项目中使用 UDS 时：
+
+- 保持 UDS CLI 为最新版本
+- 采用前审阅标准（特别是 `security-standards.md`）
+- 定期对项目执行 `npm audit`
+- 遵循 `core/security-standards.md` 定义的安全标准

package/bundled/locales/zh-CN/core/acceptance-criteria-traceability.md

@@ -0,0 +1,301 @@
+---
+source: ../../../core/acceptance-criteria-traceability.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-03-23
+status: current
+---
+
+# 验收标准可追溯性规范
+
+> **语言**: [English](../../../core/acceptance-criteria-traceability.md) | 简体中文
+
+**适用范围**: 所有使用规格驱动或测试驱动工作流程的软件项目
+**Scope**: universal
+
+---
+
+## 概述
+
+验收标准可追溯性规范定义了如何追踪验收标准（AC）、测试实现与覆盖状态之间的关系。本规范确保每个 AC 都可被验证测试，并提供标准化的覆盖率分析报告格式。
+
+## 参考资料
+
+| 标准 / 来源 | 内容 |
+|------------|------|
+| ISO/IEC/IEEE 29119-3 | 测试文档 — 可追溯性矩阵 |
+| IEEE 830 | 软件需求规格 — 可追溯性 |
+| ISTQB Foundation | 基于需求的测试 |
+| INVEST 原则 | 验收标准品质 |
+
+---
+
+## AC 对测试的可追溯性矩阵
+
+### 标准矩阵格式
+
+| AC-ID | 测试文件 | 测试名称 | 状态 | 备注 |
+|-------|---------|---------|------|------|
+| AC-1 | `tests/auth.test.ts` | `should login with valid credentials` | ✅ 已覆盖 | |
+| AC-2 | `tests/auth.test.ts` | `should reject invalid credentials` | ✅ 已覆盖 | |
+| AC-3 | — | — | ❌ 未覆盖 | 被 API 依赖性阻挡 |
+| AC-4 | `tests/auth.test.ts` | `should lock account after 5 failures` | ⚠️ 部分覆盖 | 缺少边界情况 |
+
+### 矩阵字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `AC-ID` | 是 | 规格中的唯一标识码（例如 AC-1、AC-2） |
+| `Test File` | 是（若已覆盖） | 实现此 AC 的测试文件路径 |
+| `Test Name` | 是（若已覆盖） | 测试用例或 describe 区块的名称 |
+| `Status` | 是 | 覆盖状态：`covered`、`partial`、`uncovered` |
+| `Notes` | 否 | 补充信息（阻挡因素、依赖性等） |
+
+### 连结惯例
+
+测试 **必须** 使用标准注释引用其来源 AC：
+
+```typescript
+// TypeScript/JavaScript
+describe('AC-1: User login with valid credentials', () => {
+  // @AC AC-1
+  // @SPEC SPEC-001
+  it('should redirect to dashboard on successful login', () => { ... });
+});
+```
+
+```python
+# Python
+class TestAC1_UserLogin:
+    """AC-1: User login with valid credentials
+    @AC AC-1
+    @SPEC SPEC-001
+    """
+    def test_redirect_to_dashboard(self): ...
+```
+
+```gherkin
+# BDD Feature
+@SPEC-001 @AC-1
+Scenario: User login with valid credentials
+```
+
+---
+
+## 覆盖状态定义
+
+### 状态分类
+
+| 状态 | 符号 | 定义 | 判断标准 |
+|------|------|------|---------|
+| **已覆盖** | ✅ | AC 已完整测试 | AC 中所有条件都有对应的测试断言 |
+| **部分覆盖** | ⚠️ | AC 已部分测试 | 部分条件已测试，但缺少边界情况或执行路径 |
+| **未覆盖** | ❌ | AC 没有测试 | 没有任何测试用例引用此 AC |
+
+### 覆盖率计算
+
+```
+AC Coverage % = (covered_count / total_ac_count) × 100
+
+Where:
+  covered_count = count of AC with status "covered"
+  total_ac_count = total number of AC in specification
+  partial counts as 0.5 for coverage calculation
+```
+
+### 计算范例
+
+```
+SPEC-001: 8 AC total
+  - 5 covered (✅)
+  - 2 partial (⚠️)
+  - 1 uncovered (❌)
+
+Coverage = (5 + 2×0.5) / 8 = 6/8 = 75%
+```
+
+---
+
+## 品质门槛
+
+### 默认门槛
+
+| 门槛 | 数值 | 强制执行 |
+|------|------|---------|
+| **最低 AC 覆盖率** | 100% | 正式发布前必须达到 |
+| **签入最低要求** | 80% | 功能分支合并前必须达到 |
+| **警告级别** | 60% | 触发覆盖率警告 |
+
+### 可配置门槛
+
+项目 **可以** 在配置文件中自定义门槛：
+
+```json
+{
+  "acCoverage": {
+    "minimum": 100,
+    "checkinMinimum": 80,
+    "warningLevel": 60,
+    "partialWeight": 0.5
+  }
+}
+```
+
+### 门槛例外
+
+覆盖率要求的例外情况 **必须** 记录在案：
+
+| 例外类型 | 允许时机 | 必要文件 |
+|---------|---------|---------|
+| 外部依赖性阻挡 | 第三方 API 无法使用 | Issue 连结 + 时程 |
+| 基础设施限制 | 测试环境限制 | 解决方案计划 |
+| 延后至下一迭代 | 已与利害关系人确认 | Ticket 引用 |
+
+---
+
+## AC 覆盖率报告格式
+
+### 标准报告结构
+
+```markdown
+# AC Coverage Report
+
+**Specification**: SPEC-001 — User Authentication
+**Generated**: 2026-03-23
+**Coverage**: 75% (6/8 AC)
+
+## Summary
+
+| Status | Count | Percentage |
+|--------|-------|------------|
+| ✅ Covered | 5 | 62.5% |
+| ⚠️ Partial | 2 | 25.0% |
+| ❌ Uncovered | 1 | 12.5% |
+
+## Traceability Matrix
+
+| AC-ID | Description | Status | Test Reference |
+|-------|-------------|--------|----------------|
+| AC-1 | Login with valid credentials | ✅ | auth.test.ts:15 |
+| AC-2 | Reject invalid credentials | ✅ | auth.test.ts:32 |
+| AC-3 | Rate limit login attempts | ⚠️ | auth.test.ts:48 (missing edge case) |
+| ...   | ...                        | ... | ... |
+
+## Gaps
+
+### Uncovered AC
+- **AC-8**: Social login integration — Blocked by OAuth provider sandbox
+
+### Partial AC
+- **AC-3**: Rate limit — Missing test for concurrent requests
+- **AC-6**: Session timeout — Missing test for background tab behavior
+
+## Action Items
+1. [ ] AC-8: Set up OAuth sandbox environment (ETA: 2026-03-25)
+2. [ ] AC-3: Add concurrent request test
+3. [ ] AC-6: Add background tab test
+```
+
+### 机器可读格式
+
+```json
+{
+  "specId": "SPEC-001",
+  "specName": "User Authentication",
+  "generatedAt": "2026-03-23T10:00:00Z",
+  "coverage": {
+    "percentage": 75,
+    "covered": 5,
+    "partial": 2,
+    "uncovered": 1,
+    "total": 8
+  },
+  "matrix": [
+    {
+      "acId": "AC-1",
+      "description": "Login with valid credentials",
+      "status": "covered",
+      "testFile": "tests/auth.test.ts",
+      "testName": "should login with valid credentials",
+      "testLine": 15
+    }
+  ]
+}
+```
+
+---
+
+## 自动规格生成品质规则
+
+### AC 品质要求
+
+当从 PRD、用户故事或需求自动生成规格时，所生成的 AC **必须** 符合以下品质标准：
+
+| 标准 | 说明 | 验证方式 |
+|------|------|---------|
+| **具体（Specific）** | AC 描述具体、可观察的行为 | 不使用模糊用语（「应该运作正常」、「够快」） |
+| **可衡量（Measurable）** | AC 有可量化或可验证的结果 | 包含预期数值、状态或行为 |
+| **可达成（Achievable）** | AC 在技术上可行 | 引用已知的 API、数据或能力 |
+| **相关（Relevant）** | AC 与功能目的相关 | 对应用户需求或业务需求 |
+| **可测试（Testable）** | AC 可通过测试验证 | 可以用 Given-When-Then 表达 |
+
+### 规格生成 I/O 契约
+
+#### 输入格式
+
+| 输入类型 | 必要字段 | 范例 |
+|---------|---------|------|
+| PRD | 标题、说明、用户故事 | 产品需求文档 |
+| 用户故事 | As a / I want / So that | 「As a user, I want to login...」 |
+| 功能简报 | 功能名称、目标、限制 | 功能说明文档 |
+
+#### 输出格式
+
+生成的规格 **必须** 包含：
+
+| 区段 | 必填 | 说明 |
+|------|------|------|
+| SPEC ID | 是 | 唯一标识码（例如 SPEC-001） |
+| 标题 | 是 | 功能名称 |
+| 说明 | 是 | 功能描述 |
+| 验收标准 | 是 | 编号 AC 清单（AC-1、AC-2、…） |
+| AC 格式 | 是 | Given-When-Then 或结构化条列 |
+| 可测试性标记 | 是 | 每个 AC 标记为可测试 / 不可测试 |
+
+#### 验证规则
+
+1. **AC 数量**：生成的规格 **必须** 至少有 1 个 AC
+2. **AC 唯一性**：不可有重复的 AC 描述
+3. **AC 完整性**：正常路径 + 至少 1 个错误或边界情况
+4. **AC 可测试性**：100% 的 AC 必须可测试
+5. **可追溯性**：每个 AC 都连结回来源需求
+
+---
+
+## 反模式
+
+| 反模式 | 影响 | 正确做法 |
+|-------|------|---------|
+| 测试无法追溯 | 无法验证规格覆盖率 | 测试中一律标注 AC-ID |
+| 将部分覆盖视为完整覆盖 | 对覆盖率产生错误信心 | 使用诚实的状态分类 |
+| 忽略未覆盖的 AC | 验证存在缺口 | 追踪并规划所有 AC 的覆盖工作 |
+| AC 缺乏可测试性 | 无法验证 | 确保所有 AC 都可测试 |
+| 覆盖但缺乏断言 | 测试执行但不验证任何内容 | 确认测试含有有意义的断言 |
+
+---
+
+## 相关规范
+
+- [正向推演规范](forward-derivation-standards.md) — 从 AC 生成测试
+- [规格驱动开发](spec-driven-development.md) — AC 定义格式
+- [测试规范](testing-standards.md) — 测试实现规范
+- [签入规范](checkin-standards.md) — 签入的覆盖率门槛
+- [测试治理](test-governance.md) — 完成标准
+
+---
+
+## 版本历程
+
+| 版本 | 日期 | 变更内容 |
+|------|------|---------|
+| 1.0.0 | 2026-03-18 | 初始版本 — 可追溯性矩阵、覆盖率计算、规格生成规则 |

package/bundled/locales/zh-CN/core/acceptance-test-driven-development.md

@@ -0,0 +1,47 @@
+---
+source: ../../../core/acceptance-test-driven-development.md
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-03-24
+status: current
+---
+
+> **语言**: [English](../../../core/acceptance-test-driven-development.md) | 简体中文
+
+# 验收测试驱动开发（ATDD）标准
+
+**版本**: 1.1.0
+**最后更新**: 2026-01-25
+**适用范围**: 所有采用验收测试驱动开发的项目
+**范围**: universal
+**行业标准**: 无（2003-2006 实践）
+
+---
+
+## 摘要
+
+验收测试驱动开发（ATDD）是一种传统开发方法论（2003-2006），强调在开发开始前协作定义验收条件。整个团队（业务、开发和测试）共同定义"完成"的标准，通过可执行的验收测试来表达。
+
+ATDD 的核心价值是 **Three Amigos** 协作模式，由客户/PO、开发者和测试者共同定义验收条件。ATDD 是定义验收条件的可选协作方法 — 团队也可以通过访谈、PRD 或利益相关者讨论来收集需求，并达到类似效果。
+
+---
+
+**完整指南: [ATDD Guide](../../../methodologies/guides/atdd-guide.md)**
+
+---
+
+## 快速参考
+
+| 方面 | 说明 |
+|------|------|
+| **核心工作流** | 工作坊 → 提炼 → 开发 → 演示 → 完成 |
+| **核心价值** | Three Amigos 协作（PO + 开发 + QA） |
+| **测试层级** | 系统/验收测试 |
+| **参与者** | 整个团队 + 利益相关者 |
+| **工具** | FitNesse、Cucumber、Robot Framework |
+
+## 相关标准
+
+- [行为驱动开发](behavior-driven-development.md)
+- [测试驱动开发](../../../core/test-driven-development.md)
+- [规格驱动开发](../../../core/spec-driven-development.md)