universal-dev-standards 5.17.0 → 6.1.0

package/bundled/locales/zh-CN/core/pipeline-security-gates.md

@@ -0,0 +1,146 @@
+---
+source: ../../../core/pipeline-security-gates.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-07-08
+source_hash: b234d1eb2344
+status: current
+---
+
+# Pipeline Security Gates（CI Pipeline 安全检查点）
+
+> **Language**: [English](../../../core/pipeline-security-gates.md) | [繁體中文](../../zh-TW/core/pipeline-security-gates.md) | 简体中文
+
+---
+
+## 概述
+
+本标准定义嵌入 CI pipeline 各阶段的安全检查点，涵盖 SAST、DAST、SCA（含 SBOM）、密钥扫描，以及发布前的供应链签名验证，并明确规定各类发现的阻断（Block）、警告（Warn）、记录（Log）行为。
+
+---
+
+## 核心原则
+
+- **密钥扫描在 pre-commit**：所有包含密钥的提交都必须被阻断，不得例外
+- **SAST 在构建后**：Critical 和 High 等级发现阻断 pipeline
+- **SCA + SBOM 在打包阶段**：追踪依赖组件风险并生成物料清单
+- **Attestation 验证在发布前**：打包后、部署前 MUST 验证 artifact 的 checksum、签名与 SLSA provenance（消费 supply-chain-attestation 标准的产出，不得「生成 SBOM 却不验证」）
+- **DAST 在 staging 部署后**：对运行中的应用进行动态扫描
+- **安全闸门失败 = pipeline 失败**：不得视为可忽略的警告
+- **任何绕过都需审计轨迹**：禁止静默跳过安全闸门
+
+---
+
+## 安全闸门位置与配置
+
+### 1. Pre-Commit — 密钥扫描
+
+| 项目 | 说明 |
+|------|------|
+| 扫描范围 | 所有 staged 文件 |
+| 推荐工具 | gitleaks、trufflehog、detect-secrets |
+| 阻断条件 | 任何密钥模式匹配 |
+| 可跳过 | 否（`never_skip: true`） |
+
+**重要**：此闸门必须在代码进入版本控制前执行，一旦密钥进入 git 历史便需要完整的密钥轮换流程。
+
+---
+
+### 2. Post-Build — SAST（静态应用安全测试）
+
+| 项目 | 说明 |
+|------|------|
+| 扫描范围 | 源代码 + 构建产出物 |
+| 推荐工具 | semgrep、codeql、sonarqube |
+| 阻断条件 | Critical、High |
+| 警告条件 | Medium |
+| 仅记录 | Low、Info |
+
+---
+
+### 3. Package Stage — SCA + SBOM
+
+| 项目 | 说明 |
+|------|------|
+| 扫描范围 | 依赖组件 + 容器镜像 |
+| 推荐工具 | trivy、syft、grype、dependabot |
+| 阻断条件 | Critical CVE（有可用修复版本） |
+| 警告条件 | High CVE、过时依赖组件 |
+| SBOM 格式 | SPDX、CycloneDX |
+
+**SBOM 用途**：上传至 dependency-track 或 grype-db 进行持续监控。
+
+---
+
+### 4. Pre-Deploy — Artifact Attestation Verification（供应链签名验证）
+
+| 项目 | 说明 |
+|------|------|
+| 验证范围 | 已打包的发布 artifact（文件压缩包 / 容器镜像）|
+| 推荐工具 | cosign（`verify-blob` / `verify`）、sha256sum、slsa-verifier |
+| 阻断条件 | 签名验证失败、checksum 不符、SLSA provenance 缺失 |
+| 警告条件 | SLSA 等级低于目标（公开发布建议 ≥ L2）|
+
+打包阶段（gate 3）生成 SBOM 后，**部署/发布前 MUST 验证** artifact 的完整性与来源证明，
+避免「生成了 SBOM/签名却从不验证」的假保证：比对 `checksums.txt` 的 SHA256、以
+`cosign verify-blob` 验证 SBOM 与 provenance 签名、确认 SLSA provenance 存在。完整的
+生成与验证命令、Release Bundle 结构见
+[supply-chain-attestation.md](../../../core/supply-chain-attestation.md)。
+
+---
+
+### 5. Post-Staging Deploy — DAST（动态应用安全测试）
+
+| 项目 | 说明 |
+|------|------|
+| 扫描范围 | 运行中的 staging 应用程序 |
+| 推荐工具 | ZAP、nuclei、BurpSuite Enterprise |
+| 阻断条件 | Critical |
+| 需审核批准 | High |
+| 警告条件 | Medium |
+
+---
+
+## 严重性响应矩阵
+
+| 严重性 | 动作 | 通知对象 | SLA |
+|--------|------|---------|-----|
+| Critical | 阻断 pipeline | 安全团队 | 立即 |
+| High | 阻断 pipeline | 团队负责人 | 当日 |
+| Medium | 警告 + 需审核批准 | 开发者 | 下个 Sprint |
+| Low | 仅记录 | 无 | Backlog |
+
+---
+
+## 绕过策略
+
+**默认禁止绕过**。
+
+若有特殊情况：
+- **例外流程**：需书面安全审核 + 审计日志记录
+- **紧急绕过**：有时效性令牌（time-limited token）+ 强制事后审查
+
+---
+
+## 集成点
+
+| 集成项目 | 说明 |
+|---------|------|
+| 密钥管理 | 集成 HashiCorp Vault 或 AWS Secrets Manager 进行密钥注入 |
+| SBOM 注册表 | 上传 SBOM 至 dependency-track 或 grype-db 持续监控 |
+| Artifact 签名 | 发布前以 cosign 验证 SBOM/provenance 签名与 checksum（见 supply-chain-attestation）|
+| 事故响应 | Critical 发现自动创建事故工单 |
+
+---
+
+## 相关标准
+
+- [security-standards.md](../../../core/security-standards.md) — 应用安全基础标准
+- [pipeline-integration-standards.md](../../../core/pipeline-integration-standards.md) — CI 管道集成标准
+- [deployment-standards.md](../../../core/deployment-standards.md) — 部署基础原则
+- [supply-chain-attestation.md](../../../core/supply-chain-attestation.md) — SBOM / SLSA provenance / cosign 签名的生成与验证（gate 4 消费）
+- AI 格式：[pipeline-security-gates.ai.yaml](../../../ai/standards/pipeline-security-gates.ai.yaml)
+
+---
+
+**Scope**: universal

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: 25070d0b8a98
+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