universal-dev-standards 5.17.0 → 6.1.0

package/bundled/locales/zh-CN/core/full-coverage-testing.md

@@ -0,0 +1,269 @@
+---
+source: ../../../core/full-coverage-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-07-08
+source_hash: 8ca921c68533
+status: current
+---
+
+# 全覆盖测试标准
+
+> **Language**: [English](../../../core/full-coverage-testing.md) | [繁體中文](../../zh-TW/core/full-coverage-testing.md) | 简体中文
+
+> **AI 最优化版本**: `ai/standards/full-coverage-testing.ai.yaml`
+> **XSPEC**: XSPEC-178
+> **取代**: 金字塔门槛模型（UT≥80%、IT≥70%、E2E 仅 happy-path）
+
+## 概述
+
+全覆盖测试（Full Coverage Testing）是为 AI 时代设计的行为完整性范式——在这个时代，产生测试的成本等同于产生代码的成本。传统金字塔门槛假设测试编写成本高昂——这个假设已不再成立。
+
+**核心原则**：每个 public 函数都必须测试全部三种行为路径。覆盖率以行为完整性衡量，而非百分比下限。CI 强制执行棘轮（ratchet）：覆盖率只能上升，不能下降。
+
+---
+
+## 行为完整性模型
+
+不以「80% 行覆盖率」为要求，改为要求：
+
+| 路径 | 说明 | 示例 |
+|------|-------------|---------|
+| **Happy path** | 正常输入产生正确输出 | `calculateDiscount(100, 0.1) → 90` |
+| **Edge case** | 边界值不引发非预期错误 | `calculateDiscount(0, 1.0) → 0 without throwing` |
+| **Error path** | 无效输入引发明确错误或错误状态 | `calculateDiscount(-1, 2.0) → throws ArgumentError` |
+
+每个 public 函数都需要全部三种。这以质性的、行为驱动的要求，取代「业务逻辑 80%」的目标。
+
+---
+
+## 棘轮（Ratchet）CI 策略
+
+- 当前的覆盖率基准线即为最低可接受覆盖率
+- 任何降低覆盖率的 PR 都会被阻止合并
+- 覆盖率提升时，合并后自动更新基准线
+- 没有固定百分比下限——今天达到的覆盖率就是明天的下限
+
+```bash
+# Stored in .coverage-baseline.json
+{ "line": 91.3, "branch": 88.7, "timestamp": "2026-05-06" }
+
+# PR regression → blocked
+Coverage regression: 91.3% → 89.1%. Ratchet threshold violated.
+
+# PR improvement → baseline updated
+Coverage improved: 91.3% → 92.0%. New baseline set.
+```
+
+---
+
+## 反假测试规则
+
+### 禁止：恒真断言（Tautology Assertions）
+
+无论行为如何都会通过的断言，提供的是虚假覆盖率。
+
+```typescript
+// ❌ FORBIDDEN — always passes, tests nothing
+expect(true).toBe(true)
+expect(result).toBeDefined()  // without specific value
+
+// ✅ REQUIRED — verifies actual behavior
+expect(result).toBe(90)
+expect(result).toEqual({ discount: 10, total: 90 })
+```
+
+### 禁止：Mock 核心业务逻辑
+
+Mock 自己的代码，意味着业务逻辑从未真正执行。
+
+```typescript
+// ❌ FORBIDDEN — business logic never runs
+jest.mock('./orderService', () => ({ calculateTotal: jest.fn(() => 100) }))
+
+// ✅ ALLOWED — mock only external dependencies
+// MOCK: External Stripe API — no sandbox available in CI
+jest.mock('./payment-gateway', () => ({ charge: jest.fn().mockResolvedValue({ id: 'ch_test' }) }))
+```
+
+### 必要：Mock 原因注释
+
+每个 mock 都必须说明为何该依赖不能使用真实实现。
+
+```typescript
+// ❌ FORBIDDEN — no explanation
+jest.mock('./payment-gateway')
+
+// ✅ REQUIRED — explicit reason
+// MOCK: External payment gateway — network dependency, no sandbox in CI
+jest.mock('./payment-gateway', () => ({ ... }))
+```
+
+### Mock 边界：哪些可以 Mock
+
+| ✅ 允许 Mock | ❌ 禁止 Mock |
+|-------------------|---------------------|
+| 外部 HTTP API（金流、OAuth） | 核心业务计算函数 |
+| 硬件接口（传感器、GPIO） | 自己的 service 层方法 |
+| 无测试模式的第三方 SDK | 数据库查询（改用 in-memory SQLite） |
+| Docker daemon | 自己的工具函数 |
+
+---
+
+## STUB 标记协议
+
+所有临时性/占位实现都必须（MUST）以标准 STUB 标记标示。此规则由 pre-push hooks 与 deploy.sh 强制执行。
+
+### 标记一个 STUB
+
+```typescript
+// WARNING: STUB — Remove before UAT
+async function validatePayment(card: Card): Promise<boolean> {
+  return true; // Always approve — replace with real Stripe call
+}
+```
+
+### 豁免真正的限制
+
+当某个依赖确实无法被测试时（硬件、无 sandbox 的线上 API）：
+
+```typescript
+// COVERAGE_EXEMPT: Hardware temperature sensor — no simulation available in CI
+async function readTemperature(): Promise<number> {
+  return hardwareSensor.read();
+}
+```
+
+豁免原因必须（MUST）非空且具体。
+
+### 部署闸门
+
+| 环境 | 存在 STUB | 动作 |
+|-------------|-------------|--------|
+| Feature branch push | 是 | ⚠️ 警告（不阻止） |
+| `main` branch push | 是 | ❌ 阻止 |
+| Staging deploy | 是 | ⚠️ 警告（不阻止） |
+| UAT deploy | 是 | ❌ 阻止 |
+| Production deploy | 是 | ❌ 阻止（critical log） |
+
+---
+
+## AC 可追溯性
+
+使用 `@ac` JSDoc 标签将每个测试连接到其验收标准（Acceptance Criteria）：
+
+```typescript
+/**
+ * @ac AC-US03-2
+ */
+it('should block PR when coverage regresses below baseline', () => {
+  // test body
+})
+
+// If no AC maps to this test:
+/**
+ * @ac UNTRACED
+ */
+it('helper utility returns correct format', () => { ... })
+```
+
+CI 会回报 AC 覆盖率。若超过 20% 的 AC 没有 `@ac` 标签的测试，会显示警告。
+
+---
+
+## 迁移错误路径完整性（XSPEC-288）
+
+> 属于 [XSPEC-284](https://github.com/AsiaOstrich/universal-dev-standards) 9 轴迁移完整性矩阵的**轴⑨（错误路径）**。上述三路径模型要求**每个函数**都有错误路径；本节新增**迁移专属**保证——legacy 的错误/降级/fallback 分支被**系统性**移植，而非仅抽样。
+
+### 为何三路径模型对迁移还不够
+
+每函数错误路径要求与 XSPEC-201 的错误路径快照，只验证你**想到要枚举**的错误案例。重写时 happy path 因有明确需求而被迁移，而错误分支——散落于 `try/catch` 层级、自定义异常层级、特定错误码、降级 fallback——**被整批静默遗漏**。通过的错误路径抽样**不能证明没有分支被遗漏**（与 #134 同源盲区，只是发生在错误路径层）。本节是快照机制之上的**系统性枚举 + gap 分析**层。
+
+### 步骤 1 — 机械化 legacy 异常/错误码清单（derive，R1）
+
+**机械化**枚举 legacy 错误面，而非依赖人脑回忆：
+
+| 来源 | 推导出 |
+|--------|--------|
+| `catch` / `except` / `rescue` 区块（grep） | 每个捕获的异常类型 + handler |
+| 自定义异常/错误类层级 | 声明的错误分类法 |
+| 错误/状态码（HTTP status、app 错误码、错误 enum） | 响应码面 |
+| 错误响应形状（serializer、错误 DTO） | on-the-wire 错误契约 |
+
+捕获到的清单即**错误路径待验清单**——来自 artifact 而非人脑回忆。
+
+### 步骤 2 — 系统性遗漏分支 gap 分析（oracle，R2）
+
+对步骤 1 的**每条** legacy 错误分支，验证新系统有对应 handler。无对应者标记为 `not_implemented`（XSPEC-199）并**阻止**。产出覆盖完整推导清单的**「遗漏错误分支」gap 报告**——而非仅抽样通过。
+
+```markdown
+## Error-Path Gap Report — <module>
+
+| Legacy branch (error type / code) | New-system handler | Status |
+|-----------------------------------|--------------------|--------|
+| PaymentDeclinedException → 402 | PaymentService.handleDecline | MAPPED |
+| GatewayTimeout → retry+fallback | (none found) | not_implemented — BLOCK |
+| ValidationError → 422 + field list | InputValidator | MAPPED |
+
+**Branches: N total · M mapped · K not_implemented (block if K>0)**
+```
+
+### 步骤 3 — 降级/Fallback 对等（R3）
+
+legacy 降级模式（外部服务失败时的 fallback、重试、部分结果）因仅在失败时才执行而容易被遗漏。验证新系统保留对应降级行为，避免「正常路径一致、失败时行为迥异」：
+
+- [ ] 外部服务失败的 **fallback** 行为与 legacy 一致
+- [ ] **重试**策略（次数、backoff、放弃条件）与 legacy 一致
+- [ ] **部分结果**处理与 legacy 一致（尽量返回 vs all-or-nothing）
+- [ ] **熔断器/超时**降级与 legacy 一致
+
+### 步骤 4 — 错误响应差分（oracle，R4）
+
+把 [behavior-snapshot](behavior-snapshot.md) 对等与 XSPEC-284 R5 replay 延伸至涵盖**错误响应**，而不只是 happy-path 响应。比对新旧系统：
+
+- **错误码**（HTTP status、app 错误码）
+- **消息结构**（错误 DTO 形状、字段级错误）
+- 各错误类的 **HTTP status** 映射
+
+这让隐性错误路径分歧在 cutover 时自我暴露，如同 happy-path 快照一样。
+
+**Gate 时机**：pre-UAT（gap 分析 + 降级对等）+ cutover 前后（错误响应差分）。
+
+### 重要性分级（范围指引）
+
+并非每条 legacy 错误分支都同等优先。按**生产实际触发频率**排序（呼应 #134「以生产为准」）：生产日志中实际触发过的分支优先对应；从未触发的潜在分支优先级较低但仍列入。高频生产错误分支若无新系统对应即为硬阻止。
+
+### 完整性声明（矩阵对齐）
+
+当本节声明以下三者——**derive**（步骤 1 机械化异常/错误码清单）、**oracle**（步骤 2 系统性 gap 分析 + 步骤 4 错误响应差分）、**gate 时机**（pre-UAT + cutover 前后）——即满足轴⑨。复用 XSPEC-201 错误路径快照 + 上述三路径模型——本节只新增系统性遗漏分支分析与错误响应差分，不重建测试框架。
+
+---
+
+## 从金字塔模型迁移
+
+若你的项目先前使用金字塔门槛：
+
+1. **删除** `jest.config.js` / `vitest.config.ts` 中任何硬编码的覆盖率门槛（`coverageThreshold` 选项）
+2. **安装** `.coverage-baseline.json`，以当前的覆盖率作为棘轮起点
+3. **新增** `scripts/check-coverage-ratchet.sh` 到 CI
+4. **新增** `scripts/check-stubs.sh` 到 deploy.sh 与 pre-push hook
+5. **新增** `scripts/check-anti-fake-tests.sh` 到 pre-commit 或 CI
+
+棘轮从你当前的覆盖率开始。从那一刻起，它只能上升。
+
+---
+
+## 相关标准
+
+- `testing.ai.yaml` — 测试结构、FIRST 原则、AAA 模式（金字塔门槛在此已弃用）
+- `unit-testing.ai.yaml` — 单元测试范围与组织
+- `integration-testing.ai.yaml` — 集成测试模式
+- `deployment-standards.ai.yaml` — 部署闸门需求
+- `flaky-test-management.md` — 间歇性失败处理：会 flaky 的测试**不算**通过的测试。覆盖率数字计入闸门前，间歇性失败必须（MUST）依该标准隔离/设定重试预算/根因排查——否则「全覆盖」会掩盖非确定性缺口。
+- `behavior-snapshot.md` — 错误响应差分 oracle（迁移错误路径完整性，轴⑨）
+- `migration-assistant` skill — legacy 异常/错误码 derive + 降级对等（XSPEC-288）
+- XSPEC-178 — 完整规格与实现阶段
+- XSPEC-288 — 迁移错误路径完整性（XSPEC-284 矩阵轴⑨）
+
+
+**Scope**: universal

package/bundled/locales/zh-CN/core/git-worktree.md

@@ -3,7 +3,7 @@ source: ../../../core/git-worktree.md
 source_version: 1.0.0
 translation_version: 1.0.0
 last_synced: 2026-03-24
-status: current
+status: stale
 ---
 
 > **语言**: [English](../../../core/git-worktree.md) | 简体中文

package/bundled/locales/zh-CN/core/governance-layer.md

@@ -0,0 +1,160 @@
+---
+source: ../../../core/governance-layer.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: faff51e79a15
+status: current
+---
+
+# 治理层标准
+
+> **语言**: [English](../../../core/governance-layer.md) | [繁體中文](../../zh-TW/core/governance-layer.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-05-07
+**适用范围**: 所有具有多 Agent 或多角色 AI 工作流程的软件项目
+**范畴**: universal
+**产业标准**: 无（UDS 原创）
+
+---
+
+## 目的
+
+治理层为项目中所有 Agent 与角色提供共同锚点：
+Vision（方向）→ Mission（边界 + 红线）→ Goals（可量测的 KPI）。
+
+它是 **Standard #0**：在所有其他标准之前评估。当本标准与其他领域标准发生冲突时，本标准优先。
+
+---
+
+## 三层架构
+
+### Vision（愿景）
+
+| 字段 | 要求 |
+|------|------|
+| 格式 | 单一句子，≤ 50 tokens |
+| 内容 | 长期方向；永恒不变；不含量测指标 |
+| 变更频率 | 每年审查 |
+
+**示例**：
+> "成为全球软件团队最值得信赖的 AI 开发工作流程标准。"
+
+---
+
+### Mission（使命）
+
+| 字段 | 要求 |
+|------|------|
+| 格式 | 3–5 项承诺陈述 + 红线清单（合计 ≤ 300 tokens） |
+| 内容 | 我们做什么 / 不做什么；含触发条件与处置动作的红线 |
+| 变更频率 | 每季审查 |
+
+**红线必备字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | 字符串 | 唯一标识符（例如：R1、GUARD-001） |
+| `category` | 字符串 | 分类（quality / safety / compliance / ethics） |
+| `clause` | 字符串 | 人类可读的禁止或要求陈述 |
+| `action` | 枚举 | `block` \| `warn` \| `escalate_to_human` 之一 |
+
+---
+
+### Goals（目标）
+
+| 字段 | 要求 |
+|------|------|
+| 格式 | KPI 清单，≤ 500 tokens |
+| 变更频率 | 每个 Sprint 校准 |
+| 可否证性 | 每个 KPI 必须可量测——禁止使用「改善」、「提升」等模糊词汇 |
+
+**KPI 必备字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | 字符串 | 唯一标识符（例如：KPI-01） |
+| `metric_name` | 字符串 | 追踪的指标名称 |
+| `threshold` | 字符串 | 量化目标（例如：≥ 95%、< 200 ms） |
+| `measurement_method` | 字符串 | 量测方式与时机 |
+
+---
+
+## 优先顺序
+
+治理层对所有其他标准具有**更高优先权**。冲突时的解析顺序：
+
+1. **治理层**（本标准）— 方向、红线、KPI
+2. **领域标准**（测试、提交信息、部署等）
+3. **项目特定覆盖**（本地 `.standards/` 定制化）
+
+---
+
+## 红线格式
+
+每条红线必须包含所有必备字段。执行动作说明：
+
+| 动作 | 行为 |
+|------|------|
+| `block` | 立即停止 pipeline；不继续执行 |
+| `warn` | 记录违规并继续；超过阈值时升级 |
+| `escalate_to_human` | 暂停并要求人类决策后才继续 |
+
+此外，每条红线应包含 `mission_clause_ref` 字段，参照其所强制执行的使命承诺。
+
+---
+
+## 评估器集成
+
+当项目使用 AI 评估器 Agent 时，治理层提供评分锚点：
+
+| 评估轴 | 权重 | 否决阈值 |
+|--------|------|----------|
+| 正确性 | 0.4 | < 0.3 → 不通过 |
+| 使命对齐度 | 0.3 | < 0.3 → 不通过 |
+| 目标达成度 | 0.3 | < 0.3 → 不通过 |
+
+- **mission_alignment_score**：输出与使命承诺的对齐程度
+- **goal_achievement_score**：输出推进目标 KPI 的程度
+- 任何单一评估轴低于 0.3 即触发不通过，无论加权总分为何
+
+---
+
+## 风险接受（trace_only 模式）
+
+若项目放宽人工闸门（例如 `gate.mode = trace_only`），必须在 `mission.md` 中明确撰写**风险接受条款**，包含：
+
+| 必填字段 | 说明 |
+|----------|------|
+| `date` | 接受风险的日期 |
+| `signatory` | 接受风险的人员或角色 |
+| `gates_bypassed` | 列举所有绕过的人工闸门 |
+| `risks_accepted` | 明确描述已接受的风险 |
+
+若无有效的风险接受条款，pipeline **必须拒绝启动（fail-closed）**。
+
+---
+
+## 治理文件结构
+
+采用本标准的项目应维护以下文件：
+
+```
+governance/
+├── vision.md          # 单一句子愿景陈述
+├── mission.md         # 承诺 + 红线清单
+└── goals.md           # KPI 清单（每个 Sprint 更新）
+```
+
+---
+
+## 合规检查清单
+
+- [ ] Vision 为单一句子且 ≤ 50 tokens，不含量测指标
+- [ ] Mission 有 3–5 项承诺及含所有必备字段的红线清单
+- [ ] 每条红线均有：id、category、clause、action
+- [ ] Goals 清单存在，每个 KPI 均含：id、metric_name、threshold、measurement_method
+- [ ] 没有任何 KPI 使用模糊词汇（「改善」、「提升」、「更好」）
+- [ ] 若 `gate.mode = trace_only`，`mission.md` 中存在风险接受条款
+- [ ] 所有 AI 评估器以 0.4/0.3/0.3 权重评分，且任一轴 < 0.3 即不通过