universal-dev-standards 5.16.0 → 6.0.0

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

@@ -0,0 +1,197 @@
+---
+source: ../../../core/full-coverage-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: e05fa172a6ee
+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` 标签的测试，会显示警告。
+
+---
+
+## 从金字塔模型迁移
+
+若你的项目先前使用金字塔门槛：
+
+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` — 部署闸门需求
+- XSPEC-178 — 完整规格与实现阶段
+
+
+**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 即不通过