universal-dev-standards 5.17.0 → 6.0.0

package/bundled/locales/zh-CN/core/policy-as-code-testing.md

@@ -0,0 +1,203 @@
+---
+source: ../../../core/policy-as-code-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 80f3b5726ad3
+status: current
+---
+
+# Policy as Code 测试标准
+
+> **Language**: [English](../../../core/policy-as-code-testing.md) | [繁體中文](../../zh-TW/core/policy-as-code-testing.md) | 简体中文
+
+> 标准 ID：`policy-as-code-testing`
+> 版本：v1.0.0
+> 最后更新：2026-05-05
+
+---
+
+## 为什么需要测试 Policy as Code？
+
+OPA（Open Policy Agent）的 Rego policy 控制 AI Agent 能否执行生产环境操作。**未测试的 policy = 静默的安全漏洞。**
+
+Policy as Code 的特殊风险：
+1. **边界条件难以推理**：`reversible: false` + `target_env: "prod"` 组合是否触发？
+2. **类型错误只在运行时爆发**：`array.concat()` 用在 set 类型 → 静默失效
+3. **Fail-Open 风险**：评估失败若返回 `allow: true`，攻击者可触发未定义路径
+4. **Policy 改动回归**：新增一条 rule 可能意外放行原本被拦截的案例
+
+---
+
+## 一、OPA 测试框架
+
+### 测试规则格式
+
+```rego
+# 文件命名：<policy_module>_test.rego
+# Package：<policy_package>_test
+package governance.guardian.forbidden_patterns_test
+
+import future.keywords.if
+
+# 正向测试：规则应触发（assert rule fires）
+test_drop_database_is_forbidden if {
+    data.governance.guardian.forbidden_patterns.has_forbidden_pattern with input as {
+        "plan": [{"command_type": "sql", "command": "DROP DATABASE prod_main", "reversible": false}]
+    }
+}
+
+# 负向测试：规则不应触发（assert rule does NOT fire）
+test_safe_select_is_not_forbidden if {
+    not data.governance.guardian.forbidden_patterns.has_forbidden_pattern with input as {
+        "plan": [{"command_type": "sql", "command": "SELECT * FROM users LIMIT 10", "reversible": true}]
+    }
+}
+```
+
+### 执行方式
+
+```bash
+# OPA 已安装时
+opa test src/guardian/policies/ -v
+
+# 通过 Docker（无需安装 OPA）
+docker run --rm \
+  -v "$(pwd)/src/guardian/policies:/policies:ro" \
+  openpolicyagent/opa:latest-static \
+  test /policies -v
+```
+
+---
+
+## 二、每个 Policy Module 的最低测试要求
+
+| 类型 | 最少案例 | 说明 |
+|------|---------|------|
+| ALLOW cases | 2 | 应该通过的正常操作 |
+| DENY cases | 3 | 应该被拦截的危险操作 |
+| Boundary cases | 1 | 边界条件（如 reversible=true vs. false）|
+| Integration（main policy）| 2 | 集成 main.rego 的允许 + 拒绝路径 |
+
+---
+
+## 三、Policy Module 设计原则
+
+### 3.1 Fail-Closed 默认
+
+```rego
+# main.rego 必须包含以下默认值
+default allow = false
+
+allow if {
+    not data.governance.guardian.forbidden_patterns.has_forbidden_pattern
+    not data.governance.guardian.env_policy.prod_violation
+    not data.governance.guardian.logic_constraints.has_logic_violation
+}
+```
+
+任何 `undefined` 评估结果都应返回 DENY，不能返回 ALLOW。
+
+### 3.2 使用 Set（不要 array.concat）
+
+OPA ≥ 0.40 的类型系统严格区分 array 和 set。`violations` partial rule 是 set 类型，**不可用 `array.concat()`**。
+
+```rego
+# ✅ 正确：partial set rule 收集 violations
+deny_reasons[r] if { r := data.governance.guardian.forbidden_patterns.violations[_] }
+deny_reasons[r] if { r := data.governance.guardian.env_policy.violations[_] }
+deny_reasons[r] if { r := data.governance.guardian.logic_constraints.violations[_] }
+
+# ❌ 错误：array.concat 用在 set 上 → rego_type_error
+# deny_reasons := array.concat(violations1, violations2)
+```
+
+### 3.3 禁止解析自由文本字段
+
+Policy 决策**不得依赖** `intent`、`description`、`annotation` 等用户可控文本字段。
+
+```rego
+# ❌ 危险：解析 intent 字段 → Prompt Injection 攻击面（OWASP LLM01）
+allow if { contains(input.intent, "EMERGENCY") }
+
+# ✅ 安全：只使用结构化字段
+allow if {
+    input.target_env != "prod"
+    every step in input.plan { step.reversible == true }
+}
+```
+
+### 3.4 一个 Module 管一个关注点
+
+```
+policies/
+  forbidden_patterns.rego      ← 禁止指令模式
+  forbidden_patterns_test.rego
+  env_policy.rego              ← 环境特定规则（prod 保护）
+  env_policy_test.rego
+  logic_constraints.rego       ← 逻辑一致性（stop+start 用 restart）
+  logic_constraints_test.rego
+  risk_gate.rego               ← 风险分数阈值
+  risk_gate_test.rego
+  main.rego                    ← 集成所有 module，Fail-Closed
+  main_test.rego               ← 集成测试
+```
+
+---
+
+## 四、CI 集成
+
+### GitHub Actions 步骤
+
+```yaml
+- name: Test OPA Rego Policies
+  run: |
+    docker run --rm \
+      -v "${{ github.workspace }}/src/guardian/policies:/policies:ro" \
+      openpolicyagent/opa:latest-static \
+      test /policies -v
+```
+
+### npm script
+
+```json
+{
+  "test:policy": "docker run --rm -v \"$(pwd)/src/guardian/policies:/policies:ro\" openpolicyagent/opa:latest-static test /policies -v"
+}
+```
+
+---
+
+## 五、质量闸门
+
+| 闸门 | 阈值 | 强制程度 |
+|------|------|---------|
+| OPA 测试通过率（CI） | 100%（所有 test_ rule 通过）| Block merge |
+| Root policy Fail-Closed | `default allow = false` 存在 | Block merge |
+| 每个 policy module 有 _test.rego | 每个 .rego 有对应测试 | Advisory |
+
+---
+
+## 六、反模式（Anti-patterns）
+
+| 反模式 | 问题 | 正确做法 |
+|--------|------|---------|
+| `array.concat()` 用在 violations（set 类型）| OPA 类型错误 | 改用 partial set rule |
+| Root policy 缺少 `default allow = false` | Fail-Open 漏洞 | 加入 default |
+| Intent 字段参与安全决策 | Prompt Injection 攻击面 | 只用结构化字段 |
+| 只测试 DENY（无 ALLOW 测试）| 无法检测过度限制 | 加入 ALLOW 案例 |
+| _test.rego 只在本地运行，不在 CI | policy 改动无安全网 | CI 加 `opa test` step |
+
+---
+
+## 参考标准
+
+- [OPA Testing Guide](https://www.openpolicyagent.org/docs/latest/policy-testing/)
+- NIST SP 800-204C — Attribute-based Access Control
+- [UDS `secure-op.ai.yaml`](../../../core/secure-op.md) — AI Agent 安全操作六大支柱
+- [UDS `adversarial-test.ai.yaml`](../../../core/adversarial-test.md) — 对抗性测试（OWASP LLM01）
+- [UDS `container-security.ai.yaml`](../../../core/container-security.md) — 容器安全（OPA Sidecar 部署）
+
+---
+
+**Scope**: universal

package/bundled/locales/zh-CN/core/privacy-standards.md

@@ -3,7 +3,7 @@ source: ../../../core/privacy-standards.md
 source_version: 1.0.0
 translation_version: 1.0.0
 last_synced: 2026-04-10
-status: current
+status: stale
 ---
 
 # 隐私标准

package/bundled/locales/zh-CN/core/project-context-memory.md

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

package/bundled/locales/zh-CN/core/prompt-regression.md

@@ -0,0 +1,88 @@
+---
+source: ../../../core/prompt-regression.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 418f48be7045
+status: current
+---
+
+# Prompt 回归测试标准
+
+> **语言**: [English](../../../core/prompt-regression.md) | [繁體中文](../../zh-TW/core/prompt-regression.md) | 简体中文
+
+---
+
+## 概述
+
+AI 代理的 prompt 即代码。未预期的变更会悄悄降低代理行为质量，却不会触发类型错误或单元测试失败。Prompt 回归测试利用 SHA-256 黄金校验和（golden checksum）检测任何修改，强制开发者明确确认并记录每次 prompt 变更。
+
+## 为什么要使用校验和
+
+- 仅有 diff 不能阻止 CI 流程——校验和可以
+- Prompt 是大型 Markdown 文件；细微的编辑（空白字符、标点符号）都可能改变模型行为
+- 校验和更新 + 说明注释会建立每次 prompt 变更原因的审计轨迹
+
+## 实现方式
+
+### 1. 计算初始校验和
+
+```bash
+for f in agents/*/prompt.md; do
+  echo -n "$f: "
+  sha256sum "$f" | cut -d' ' -f1
+done
+```
+
+### 2. 黄金校验和测试（Vitest）
+
+```typescript
+// SPDX-License-Identifier: AGPL-3.0-only
+import { createHash } from "crypto"
+import { readFileSync } from "fs"
+import { join } from "path"
+import { describe, it, expect } from "vitest"
+
+// 仅在 prompt 变更为刻意行为时才更新这些值。
+// 在同一行加上说明 WHY prompt 发生变更的注释。
+const GOLDEN_CHECKSUMS: Record<string, string> = {
+  architect: "98017d39b0e48cda88b796687d21e0f884c810805e534453a23b7ad935e4a5ef",
+  builder:   "5c2acda3e48dae771c61f55d3a5b0d5ac7383870054ef71e757714e367c50031",
+  // ... 所有代理
+}
+
+describe("Agent prompt regression (XSPEC-162)", () => {
+  for (const [agent, expected] of Object.entries(GOLDEN_CHECKSUMS)) {
+    it(`agents/${agent}/prompt.md checksum matches golden`, () => {
+      const filePath = join(__dirname, "..", "..", "agents", agent, "prompt.md")
+      const content = readFileSync(filePath)
+      const actual = createHash("sha256").update(content).digest("hex")
+      expect(actual, `Prompt for '${agent}' changed unexpectedly. If intentional, update GOLDEN_CHECKSUMS with a comment.`).toBe(expected)
+    })
+  }
+})
+```
+
+### 3. CI 集成
+
+校验和测试作为标准 `npm run test:coverage` 闸门的一部分执行（已通过 XSPEC-156 强制执行）。不需要额外的 CI 步骤。
+
+### 4. 更新校验和
+
+当 prompt 变更为刻意行为时：
+
+```typescript
+// 之前：
+architect: "98017d39...",  // updated 2026-05-05: added Guardian policy XSPEC-160 reference
+```
+
+说明注释是必填的。在代码审查时，应拒绝未附说明注释即更新校验和的 PR。
+
+## 相关标准
+
+- [LLM 输出验证](../../../core/llm-output-validation.md) — schema 层级验证
+- [对抗性测试](../../../core/adversarial-test.md) — 红队语料库
+- [测试标准](../../../core/testing-standards.md) — 整体测试金字塔
+
+
+**Scope**: universal

package/bundled/locales/zh-CN/core/property-based-testing.md

@@ -0,0 +1,87 @@
+---
+source: ../../../core/property-based-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 13f5eba04aef
+status: current
+---
+
+# Property-Based Testing 标准
+
+> **语言**: [English](../../../core/property-based-testing.md) | [繁體中文](../../zh-TW/core/property-based-testing.md) | 简体中文
+
+## 概述
+
+基于示例的测试只能验证开发者想得到的用例。Property-based testing 反转了这一思路：你定义一个不变量（"分数永远介于 0 到 100 之间"），框架会生成数百个输入来尝试推翻它。当找到失败的输入时，框架会将其收缩（shrink）为最小反例。
+
+## 使用时机
+
+| 使用 Property 测试 | 使用示例测试 |
+|-------------------|------------------|
+| 纯数学函数 | 复杂业务逻辑 |
+| 解析器 / 序列化器 | 集成路径 |
+| 分数截断 / 四舍五入 | UI 行为 |
+| 哈希 / 编码 | 数据库操作 |
+| 安全验证器 | 外部 API 调用 |
+
+## 工具：fast-check（TypeScript）
+
+```bash
+npm install --save-dev fast-check
+```
+
+```typescript
+import fc from "fast-check"
+import { describe, it, expect } from "vitest"
+import { classifyTokenZone, TOKEN_BUDGET } from "../types/index.js"
+
+describe("classifyTokenZone property: result is always a valid zone", () => {
+  it("for any ratio in [0, 2], returns a valid TokenBudgetZone", () => {
+    fc.assert(
+      fc.property(
+        fc.float({ min: 0, max: 2, noNaN: true }),
+        (ratio) => {
+          const zone = classifyTokenZone(ratio)
+          return ["safe", "warning", "danger", "blocking"].includes(zone)
+        }
+      ),
+      { numRuns: 1000 }
+    )
+  })
+})
+```
+
+## Guardian scoreReviewable 属性
+
+需要测试的关键不变量：
+
+| 属性 | 说明 |
+|----------|-------------|
+| **范围截断** | `score` 永远在 `[0, 100]` 范围内 |
+| **确定性** | 相同输入永远产生相同分数 |
+| **单调性** | 对相同操作，prod > staging > dev |
+| **非负性** | `breakdown` 的值全部 >= 0 |
+
+## 反例收缩（Counterexample Shrinking）
+
+当 fast-check 找到失败用例时，会自动收缩：
+
+```
+Original failure: { target_env: "prod", command: "rm -rf /tmp/xyz123...", ... }
+Shrunk to:        { target_env: "prod", command: "rm", ... }
+```
+
+从错误消息中保存 seed 以便复现：
+```typescript
+fc.assert(property, { seed: 1234567890 })
+```
+
+## 相关标准
+
+- [Mutation Testing 标准](mutation-testing.md) — PBT 的互补
+- [测试标准](testing-standards.md) — 整体测试金字塔
+- [Adversarial Test 标准](adversarial-test.md) — 以安全为导向的 fuzzing
+
+
+**Scope**: universal

package/bundled/locales/zh-CN/core/release-quality-manifest.md

@@ -0,0 +1,207 @@
+---
+source: ../../../core/release-quality-manifest.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 9ab9b61963df
+status: current
+---
+
+# Release Quality Manifest（发布质量清单）
+
+> **语言**: [English](../../../core/release-quality-manifest.md) | [繁體中文](../../zh-TW/core/release-quality-manifest.md) | 简体中文
+
+## 概述
+
+Release Quality Manifest（RQM）是由 CI 为每次发布自动生成的机器可读文档。它将所有质量门禁的结果汇总为单一产物，作为发布就绪度的权威证据——既供内部 go/no-go 自动化使用，也供客户审计使用。
+
+## 为什么需要 Manifest？
+
+没有 manifest 时，质量证据会散落在 CI 日志、覆盖率 HTML 报告、SARIF 文件与容器扫描摘要之中。当客户问"这个发布是怎么测试的？"，答案要么是"相信我们"，要么是一场 45 分钟的手动汇总作业。
+
+Release Quality Manifest 让质量证据变得：
+- **汇总化**：一个文件，所有门禁
+- **机器可读**：下游工具可以解析并强制执行
+- **带时间戳且绑定 commit**：与特定发布产物绑定
+- **可与客户共享**：可直接附加到发布包
+
+## Schema
+
+RQM 目前覆盖 **16 个质量维度**，与 `release-readiness-gate.md` 对齐。自动化门禁出现在此处；人工验证的门禁则出现在 Release Readiness Sign-off 文档中。
+
+```yaml
+release: app-commercial-1.2.0
+generated_at: "2026-05-05T04:00:00Z"
+commit: "abc1234"
+gates:
+  # ── Automated quality gates ──────────────────────────────
+  unit_coverage:
+    actual: "73%"
+    target: "80%"
+    status: warn        # within 10pp of target → warn, not fail
+  mutation_score:
+    actual: "62%"
+    target: "60%"
+    status: pass
+  sca_critical_cve:
+    actual: 0
+    target: 0
+    status: pass
+  sca_high_cve:
+    actual: 0
+    target: 0
+    status: pass
+  sast_high:
+    actual: 0
+    target: 0
+    status: pass
+  e2e_pass_rate:
+    actual: "96%"
+    target: "95%"
+    status: pass
+  container_cve_critical:
+    actual: 0
+    target: 0
+    status: pass
+  image_signed:
+    actual: true
+    target: true
+    status: pass
+  sbom_present:
+    actual: true
+    target: true
+    status: pass
+  # ── Extended dimensions (aligned with release-readiness-gate.md) ──
+  a11y_critical:             # Dimension 3: axe-core critical violations
+    actual: 0
+    target: 0
+    status: pass
+  a11y_serious:              # Dimension 3: axe-core serious violations
+    actual: 0
+    target: 0
+    status: pass
+  contract_drift:            # Dimension 4: consumer contracts failing (n/a if no consumers)
+    actual: 0
+    target: 0
+    status: pass             # or "n/a" if no API consumers
+  cross_flow_cuj_pass_rate:  # Dimension 6: critical user journey pass rate
+    actual: "100%"
+    target: "95%"
+    status: pass
+  browser_tier1_pass_rate:   # Dimension 9: Tier-1 browser matrix (n/a for non-frontend)
+    actual: "100%"
+    target: "100%"
+    status: pass             # or "n/a" for CLI/backend
+  capacity_headroom_cpu_pct: # Dimension 10: CPU headroom at projected peak (n/a for small projects)
+    actual: "42%"
+    target: "30%"
+    status: pass             # or "n/a" for small-scale projects
+  smoke_pass_rate:           # Dimension 14: post-deploy smoke (populated after staging deploy)
+    actual: "100%"
+    target: "100%"
+    status: pass
+  flow_gate_report:          # Dimension 16: Multi-Gate Flow verification
+    gate_0_complete: true    # all flows with ≥3 steps have §2.4 + §9.4 filled
+    gate_1_pr_coverage: true # all PRs touching flows include terminal-state tests
+    gate_3_ci_pass: true     # Decision Table CI all green; branch coverage ≥ 90%
+    gate_4_uat_signoff: true # UAT sign-off table signed
+    status: pass
+overall: WARN   # worst gate status across all dimensions (2 warns, no fails)
+```
+
+## 状态语义
+
+| 状态 | 含义 | 行动 |
+|--------|---------|--------|
+| `pass` | 达到或超过目标 | 无需任何行动 |
+| `warn` | 在可接受偏差范围内（见各门禁策略） | 记录原因；不阻断发布 |
+| `fail` | 低于硬性下限 | **阻断发布** |
+
+### 各门禁硬性下限
+
+| 门禁 | Warn 区间 | Fail 阈值 | Release Readiness 维度 |
+|------|-----------|----------------|----------------------------|
+| unit_coverage | target - 10pp 至 target | 低于 target - 10pp | （核心 RQM） |
+| mutation_score | target - 5pp 至 target | 低于 target - 5pp | （核心 RQM） |
+| sca_critical_cve | — | 任何 critical CVE = fail | Dim 2（安全） |
+| container_cve_critical | — | 任何 critical CVE = fail | Dim 2（安全） |
+| e2e_pass_rate | target - 3pp 至 target | 低于 target - 3pp | （核心 RQM） |
+| a11y_critical | — | > 0 = fail | Dim 3（a11y） |
+| a11y_serious | 项目阈值 | 项目阈值 + 1-2 | Dim 3（a11y） |
+| contract_drift | — | 任何红灯 consumer contract = fail（若 n/a：跳过） | Dim 4（Contract） |
+| cross_flow_cuj_pass_rate | 90–95% | < 90% | Dim 6（跨流程回归） |
+| browser_tier1_pass_rate | — | < 100%（若 n/a：跳过） | Dim 9（浏览器兼容性） |
+| capacity_headroom_cpu_pct | 20–30% | < 20%（若 n/a：跳过） | Dim 10（容量） |
+| smoke_pass_rate | — | 任何 smoke 失败 = fail | Dim 14（Smoke） |
+| flow_gate_report | gate_3_ci_pass=false | gate_0_complete=false 或 gate_4_uat_signoff=false | Dim 16（Multi-Gate Flow） |
+
+## 自动生成
+
+在所有门禁 job 完成后于 CI 生成 manifest：
+
+```bash
+#!/usr/bin/env bash
+# scripts/generate-quality-manifest.sh
+set -euo pipefail
+
+COVERAGE=$(node -e "
+  const r = JSON.parse(require('fs').readFileSync('coverage/coverage-summary.json'));
+  console.log(r.total.lines.pct.toFixed(1) + '%')
+")
+
+MUTATION=$(node -e "
+  const r = JSON.parse(require('fs').readFileSync('reports/mutation/mutation-testing-report.json'));
+  console.log(r.metrics.mutationScore.toFixed(1) + '%')
+")
+
+CRITICAL_CVE=$(jq '[.Results[]?.Vulnerabilities[]? | select(.Severity == "CRITICAL")] | length' trivy-report.json)
+
+cat > quality-manifest.yaml <<YAML
+release: ${RELEASE_TAG}
+generated_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+commit: "${GITHUB_SHA:-$(git rev-parse HEAD)}"
+gates:
+  unit_coverage:
+    actual: "${COVERAGE}"
+    target: "80%"
+    status: $([ $(echo "$COVERAGE" | tr -d '%') -ge 80 ] && echo pass || echo warn)
+  sca_critical_cve:
+    actual: ${CRITICAL_CVE}
+    target: 0
+    status: $([ "$CRITICAL_CVE" -eq 0 ] && echo pass || echo fail)
+overall: $(grep -q "fail" quality-manifest.yaml && echo FAIL || grep -q "warn" quality-manifest.yaml && echo WARN || echo PASS)
+YAML
+```
+
+## 面向客户的摘要
+
+在 YAML 之外同时生成 Markdown 表格，以便纳入 release notes：
+
+```markdown
+## Release Quality Gates — app-commercial-1.2.0
+
+| Gate | Actual | Target | Status |
+|------|--------|--------|--------|
+| Unit Test Coverage | 73% | 80% | ⚠️ WARN |
+| Mutation Score | 62% | 60% | ✅ PASS |
+| Critical CVEs | 0 | 0 | ✅ PASS |
+...
+| **Overall** | | | ⚠️ WARN |
+```
+
+## 反模式
+
+- **手动编写 manifest** —— 违背初衷；必须由工具输出生成
+- **对关键安全门禁使用 warn** —— `sca_critical_cve` 与 `container_cve_critical` 是二元判定
+- **在所有门禁跑完之前生成 manifest** —— 数值必须反映实际结果，而非估计值
+- **未将 manifest 附加到发布产物** —— 只存在于 git 历史中的 manifest 客户无法获取
+
+## 另请参阅
+
+- `verification-evidence.ai.yaml` — 审计证据原则
+- `supply-chain-attestation.ai.yaml` — SBOM 与 provenance
+- `testing.ai.yaml` — 整体测试策略
+- `deployment-standards.ai.yaml` — 发布门禁集成
+
+
+**Scope**: universal