@umacloud/knowledge 1.0.1

package/00-governance/governance-capabilities.md

@@ -0,0 +1,557 @@
+---
+id: governance-capabilities
+title: UmaDev 治理能力全景图
+domain: 00-governance
+category: governance-capabilities.md
+difficulty: intermediate
+tags: [00-governance, capabilities, engine, governance, knowledge, rule, tracker, validation]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# UmaDev 治理能力全景图
+
+> 版本: 2.1.6+ | 最后更新: 2026-03-28
+
+## 1. 概述
+
+UmaDev 的核心定位是 **AI Coding 治理层** —— 它不拥有模型端点，而是在 AI 编码宿主（Claude Code、Cursor、Windsurf 等）之上提供标准化的工程流水线协议、质量门禁和交付审计。
+
+2.1.6 版本引入了 5 项治理能力增强，将治理从"阶段性检查"升级为"全链路可编程治理"：
+
+| 能力 | 模块 | 核心价值 |
+|------|------|----------|
+| Validation Rule Engine | `umadev/reviewers/validation_rules.py` | 可编程质量规则，YAML 定义，pipeline 任意阶段插拔 |
+| Knowledge Tracker | `umadev/knowledge_tracker.py` | 知识引用透明化，覆盖率可量化 |
+| Prompt Templates | `umadev/creators/prompt_templates.py` | Prompt 版本化管理，可追溯可回滚 |
+| ADR Generator | `umadev/creators/adr_generator.py` | 架构决策自动记录，技术选型有据可查 |
+| Pipeline Metrics | `umadev/metrics/pipeline_metrics.py` | DORA + Rework Rate，效能可度量 |
+
+统一由 **Pipeline Governance** (`umadev/orchestrator/governance.py`) 集成管理。
+
+---
+
+## 2. 设计理念
+
+### 2.1 可编程优于硬编码
+
+所有治理规则通过 YAML 或 Markdown 文件定义，而非代码内嵌。这意味着：
+- 项目团队可以在不修改 UmaDev 源码的情况下调整治理策略
+- 规则变更可以通过 Git 追踪和 Code Review
+- 不同项目可以有不同的治理配置
+
+### 2.2 透明优于黑盒
+
+每项治理能力都会生成可读的报告和审计记录：
+- 验证规则执行结果有详细的通过/失败说明
+- 知识引用有完整的引用链路
+- 度量数据可导出为 JSON 供外部系统消费
+
+### 2.3 渐进式采纳
+
+所有治理能力默认启用但不阻断，团队可以逐步提高要求：
+- 先观察（报告模式）
+- 再告警（warning 模式）
+- 最后强制（fail 模式）
+
+### 2.4 与 Pipeline 深度集成
+
+治理能力不是独立的工具集，而是嵌入 pipeline 的每个阶段：
+
+```
+discovery ──> intelligence ──> drafting ──> redteam ──> qa ──> delivery ──> deployment
+   │              │               │            │         │        │            │
+   ▼              ▼               ▼            ▼         ▼        ▼            ▼
+ 知识追踪     知识追踪+       验证规则     验证规则   质量门禁   度量收集     度量报告
+              Prompt模板      ADR生成      红队规则   验证规则   ADR归档     最终审计
+```
+
+---
+
+## 3. Validation Rule Engine — 验证规则引擎
+
+### 3.1 概述
+
+验证规则引擎允许通过 YAML 文件定义质量检查规则，并在 pipeline 的指定阶段自动执行。内置 14 条默认规则，覆盖文档质量、代码规范、安全基线和架构合规。
+
+### 3.2 内置规则分类
+
+| 类别 | 规则数 | 示例 |
+|------|--------|------|
+| 文档质量 | 4 | PRD 必须包含用户故事、架构文档必须有组件图 |
+| 代码规范 | 3 | 函数复杂度上限、测试覆盖率下限、导入排序 |
+| 安全基线 | 4 | 无硬编码密钥、依赖漏洞扫描、OWASP Top 10 检查 |
+| 架构合规 | 3 | 分层依赖方向、API 契约一致性、数据库迁移脚本存在 |
+
+### 3.3 自定义规则编写指南
+
+自定义规则文件位置: `.umadev/rules/custom_rules.yaml`
+
+#### 规则结构
+
+```yaml
+rules:
+  - id: custom-001
+    name: "API 响应时间限制"
+    description: "所有 API 端点响应时间必须低于 500ms"
+    severity: error          # error | warning | info
+    phase: qa                # 执行阶段: discovery | drafting | redteam | qa | delivery
+    category: performance
+    condition:
+      type: metric_threshold
+      metric: api_response_time_p95
+      operator: lt
+      value: 500
+    message: "API P95 响应时间 {{actual}}ms 超过阈值 500ms"
+
+  - id: custom-002
+    name: "必须包含 CHANGELOG"
+    description: "交付包必须包含 CHANGELOG.md"
+    severity: warning
+    phase: delivery
+    category: documentation
+    condition:
+      type: file_exists
+      path: CHANGELOG.md
+    message: "交付包缺少 CHANGELOG.md 文件"
+
+  - id: custom-003
+    name: "禁止使用 eval()"
+    description: "代码中不得包含 eval() 调用"
+    severity: error
+    phase: redteam
+    category: security
+    condition:
+      type: pattern_absent
+      glob: "**/*.py"
+      pattern: "eval\\("
+    message: "检测到 eval() 调用: {{file}}:{{line}}"
+```
+
+#### 条件类型 (condition.type)
+
+| 类型 | 说明 | 必填参数 |
+|------|------|----------|
+| `file_exists` | 检查文件是否存在 | `path` |
+| `file_absent` | 检查文件不存在 | `path` |
+| `pattern_present` | 检查文件内容包含正则 | `glob`, `pattern` |
+| `pattern_absent` | 检查文件内容不包含正则 | `glob`, `pattern` |
+| `metric_threshold` | 检查度量值 | `metric`, `operator`, `value` |
+| `dependency_check` | 检查依赖版本 | `package`, `version_constraint` |
+| `custom_script` | 执行自定义脚本 | `script`, `expected_exit_code` |
+
+#### 跳过规则
+
+在 `umadev.yaml` 中配置:
+
+```yaml
+validation_rules:
+  skip_rules:
+    - custom-001    # 按 ID 跳过
+    - "doc-*"       # 按通配符跳过
+```
+
+---
+
+## 4. Knowledge Tracker — 知识引用追踪
+
+### 4.1 概述
+
+Knowledge Tracker 记录 pipeline 运行过程中引用了哪些知识文件，生成引用报告和覆盖率分析。这解决了"AI 到底参考了哪些资料"的透明性问题。
+
+### 4.2 追踪范围
+
+- `knowledge/` 目录下的所有文件
+- `output/knowledge-cache/*-knowledge-bundle.json` 缓存文件
+- Pipeline 各阶段的知识读取操作
+
+### 4.3 引用报告结构
+
+```json
+{
+  "run_id": "20260328-143022",
+  "total_knowledge_files": 142,
+  "referenced_files": 37,
+  "coverage": 0.26,
+  "by_domain": {
+    "security": { "total": 18, "referenced": 12, "coverage": 0.67 },
+    "architecture": { "total": 15, "referenced": 8, "coverage": 0.53 },
+    "frontend": { "total": 22, "referenced": 5, "coverage": 0.23 }
+  },
+  "unreferenced_critical": [
+    "knowledge/security/01-standards/owasp-top10.md",
+    "knowledge/architecture/04-antipatterns/monolith-trap.md"
+  ],
+  "reference_chain": [
+    {
+      "phase": "intelligence",
+      "file": "knowledge/security/01-standards/web-security-complete.md",
+      "sections_used": ["Authentication", "CSRF Protection"],
+      "downstream_artifacts": ["output/proj-architecture.md"]
+    }
+  ]
+}
+```
+
+### 4.4 使用方法
+
+```bash
+# 生成知识引用报告
+umadev governance knowledge-report
+
+# 查看覆盖率摘要
+umadev governance knowledge-report --summary
+
+# 检查是否达到最低覆盖率
+umadev governance knowledge-report --check --min-coverage 0.6
+```
+
+### 4.5 最佳实践
+
+1. **在 CI 中集成覆盖率检查**: 确保关键领域（安全、架构）的知识覆盖率不低于 60%
+2. **定期审查未引用文件**: 未引用的知识文件可能已过时，需要更新或归档
+3. **利用引用链路做根因分析**: 当交付质量出问题时，追溯知识引用链路可以发现是否遗漏了关键输入
+
+---
+
+## 5. Prompt Templates — Prompt 模板版本管理
+
+### 5.1 概述
+
+Pipeline 各阶段使用的 Prompt 模板存储为版本化的 Markdown 文件，位于 `umadev/templates/` 目录。这使得 Prompt 变更可追踪、可回滚、可 A/B 测试。
+
+### 5.2 目录结构
+
+```
+umadev/templates/
+├── discovery/
+│   ├── requirement_analysis.v1.md
+│   └── requirement_analysis.v2.md
+├── intelligence/
+│   ├── research_prompt.v1.md
+│   └── knowledge_synthesis.v1.md
+├── drafting/
+│   ├── prd_generation.v1.md
+│   ├── architecture_generation.v1.md
+│   └── uiux_generation.v1.md
+├── redteam/
+│   ├── security_review.v1.md
+│   └── performance_review.v1.md
+└── qa/
+    ├── quality_gate.v1.md
+    └── code_review.v1.md
+```
+
+### 5.3 模板格式
+
+```markdown
+---
+id: prd_generation
+version: 2
+created: 2026-03-15
+author: umadev
+variables:
+  - name: project_name
+    required: true
+  - name: research_summary
+    required: true
+  - name: knowledge_constraints
+    required: false
+    default: "无特殊约束"
+---
+
+# PRD Generation Prompt
+
+你正在为 {{project_name}} 生成产品需求文档。
+
+## 背景信息
+
+{{research_summary}}
+
+## 约束条件
+
+{{knowledge_constraints}}
+
+## 输出要求
+
+...
+```
+
+### 5.4 版本策略
+
+| 策略 | 说明 | 适用场景 |
+|------|------|----------|
+| `semver` | 语义化版本 (v1, v2, v3) | 默认，适合大多数项目 |
+| `date` | 日期版本 (20260328) | 频繁迭代的团队 |
+| `hash` | Git commit hash | 需要精确追溯的场景 |
+
+### 5.5 最佳实践
+
+1. **不要删除旧版本模板**: 保留历史版本用于对比和回滚
+2. **在模板 frontmatter 中记录变更原因**: 便于团队理解每次改动的动机
+3. **先在非关键阶段测试新模板**: 例如先在 discovery 阶段测试，稳定后再推广到 drafting
+4. **利用 variables 抽取可变部分**: 避免为不同项目复制整个模板
+
+---
+
+## 6. ADR Generator — 架构决策记录
+
+### 6.1 概述
+
+ADR (Architecture Decision Record) 是记录重要架构决策的轻量级文档。UmaDev 的 ADR Generator 从架构配置（`umadev.yaml` 和 `output/*-architecture.md`）中自动提取技术选型，生成标准化的 ADR 文档。
+
+### 6.2 自动提取的决策类型
+
+| 决策类型 | 数据来源 | 示例 |
+|----------|----------|------|
+| 前端框架选择 | `umadev.yaml: frontend` | ADR-001: 使用 React 作为前端框架 |
+| 后端框架选择 | `umadev.yaml: backend` | ADR-002: 使用 Node.js + Express |
+| 数据库选择 | `umadev.yaml: database` | ADR-003: 使用 PostgreSQL |
+| 部署平台 | `umadev.yaml: platform` | ADR-004: 选择 Web 平台部署 |
+| 架构模式 | `output/*-architecture.md` | ADR-005: 采用前后端分离架构 |
+| 安全方案 | Red-team 报告 | ADR-006: 实施 OWASP Top 10 防护 |
+
+### 6.3 ADR 格式 (MADR)
+
+```markdown
+# ADR-001: 使用 React 作为前端框架
+
+## 状态
+
+已接受 (Accepted)
+
+## 背景
+
+项目需要构建交互式 Web 前端，需要选择前端框架。
+团队对 React 生态有丰富经验。
+
+## 决策
+
+使用 React 18+ 配合 Vite 构建工具。
+
+## 理由
+
+- 团队熟悉度高，降低学习成本
+- 生态成熟，组件库丰富
+- Vite 提供快速的开发体验
+- TypeScript 支持完善
+
+## 后果
+
+- 正面: 开发效率高，招聘容易
+- 负面: 包体积较大，需要关注性能优化
+- 风险: React 大版本升级可能带来迁移成本
+
+## 相关 ADR
+
+- ADR-005: 前后端分离架构
+```
+
+### 6.4 使用方法
+
+```bash
+# 从当前项目配置生成所有 ADR
+umadev governance adr generate
+
+# 只生成指定类别
+umadev governance adr generate --category frontend,database
+
+# 列出已生成的 ADR
+umadev governance adr list
+
+# 导出为单一文档
+umadev governance adr export --format markdown
+```
+
+### 6.5 使用场景
+
+1. **新项目启动时**: 自动为技术选型生成 ADR，建立决策追溯基线
+2. **架构变更时**: 在修改 `umadev.yaml` 或架构文档后重新生成，记录演进历史
+3. **交付审计时**: ADR 作为交付证据包的一部分，证明技术决策经过了评估
+4. **团队 onboarding**: 新成员通过 ADR 快速了解项目的技术决策和背后的考量
+
+---
+
+## 7. Pipeline Metrics — 交付效能度量
+
+### 7.1 概述
+
+Pipeline Metrics 追踪交付效能指标，包括 DORA 四项指标和 Rework Rate。数据存储在本地，可导出供外部 BI 系统消费。
+
+### 7.2 度量指标
+
+#### DORA 四项指标
+
+| 指标 | 说明 | 数据来源 |
+|------|------|----------|
+| Deployment Frequency | 部署频率 | pipeline delivery 阶段完成次数 |
+| Lead Time for Changes | 变更前置时间 | 从 discovery 到 delivery 的耗时 |
+| Change Failure Rate | 变更失败率 | quality gate 未通过的比例 |
+| Time to Restore | 恢复时间 | 从失败到下次成功的耗时 |
+
+#### 扩展指标
+
+| 指标 | 说明 |
+|------|------|
+| Rework Rate | 返工率 — 需要重新执行的阶段占比 |
+| Knowledge Coverage | 知识覆盖率 — 来自 Knowledge Tracker |
+| Rule Pass Rate | 规则通过率 — 来自 Validation Rule Engine |
+| Gate Score Trend | 质量门禁分数趋势 |
+
+### 7.3 数据存储
+
+度量数据以 JSON 格式存储在 `output/metrics/` 目录:
+
+```
+output/metrics/
+├── pipeline-runs.jsonl        # 每次 pipeline 运行记录 (JSON Lines)
+├── dora-summary.json          # DORA 指标汇总
+└── weekly-report.json         # 周报数据
+```
+
+### 7.4 使用方法
+
+```bash
+# 显示当前项目的效能指标
+umadev governance metrics show
+
+# 显示最近 30 天的趋势
+umadev governance metrics show --period 30d
+
+# 导出为 JSON
+umadev governance metrics export --output metrics-export.json
+
+# 生成周报
+umadev governance metrics weekly-report
+```
+
+### 7.5 指标解读
+
+| 等级 | Deployment Frequency | Lead Time | Change Failure Rate | Time to Restore |
+|------|---------------------|-----------|---------------------|-----------------|
+| Elite | 按需 (每天多次) | < 1 天 | < 5% | < 1 小时 |
+| High | 每天至每周 | 1 天 - 1 周 | 5% - 10% | < 1 天 |
+| Medium | 每周至每月 | 1 周 - 1 月 | 10% - 20% | 1 天 - 1 周 |
+| Low | 每月以上 | > 1 月 | > 20% | > 1 周 |
+
+---
+
+## 8. Pipeline Governance 集成层
+
+### 8.1 概述
+
+`umadev/orchestrator/governance.py` 是治理集成层，负责：
+- 在 pipeline 各阶段自动调用对应的治理能力
+- 汇总所有治理结果生成统一报告
+- 根据配置决定是否阻断 pipeline
+
+### 8.2 阶段与治理能力映射
+
+```yaml
+governance_hooks:
+  discovery:
+    - knowledge_tracker.start_tracking
+  intelligence:
+    - knowledge_tracker.record_references
+    - prompt_templates.load_template
+  drafting:
+    - validation_rules.check("drafting")
+    - prompt_templates.load_template
+    - adr_generator.extract_decisions
+  redteam:
+    - validation_rules.check("redteam")
+  qa:
+    - validation_rules.check("qa")
+    - pipeline_metrics.record_gate_score
+  delivery:
+    - validation_rules.check("delivery")
+    - knowledge_tracker.generate_report
+    - adr_generator.finalize
+    - pipeline_metrics.record_completion
+  deployment:
+    - pipeline_metrics.record_deployment
+    - pipeline_metrics.generate_summary
+```
+
+### 8.3 统一治理报告
+
+pipeline 完成后，governance 层生成统一报告 (`output/governance-report.json`):
+
+```json
+{
+  "run_id": "20260328-143022",
+  "overall_status": "passed",
+  "validation_rules": {
+    "total": 17,
+    "passed": 15,
+    "warnings": 2,
+    "errors": 0
+  },
+  "knowledge_coverage": 0.72,
+  "adr_count": 6,
+  "pipeline_duration_minutes": 45,
+  "quality_gate_score": 92,
+  "rework_count": 1
+}
+```
+
+---
+
+## 9. Agent Checklist
+
+以下清单供 AI Agent（Claude Code、Cursor 等）在执行 UmaDev pipeline 时参考：
+
+### 9.1 Pipeline 启动前
+
+- [ ] 确认 `umadev.yaml` 中治理配置已正确设置
+- [ ] 确认 `.umadev/rules/custom_rules.yaml` 存在（如有自定义规则）
+- [ ] 确认 `knowledge/` 目录内容为最新版本
+- [ ] 确认 `umadev/templates/` 中模板版本正确
+
+### 9.2 各阶段检查
+
+- [ ] **discovery**: Knowledge Tracker 已启动追踪
+- [ ] **intelligence**: 知识引用已记录，Prompt 模板已加载
+- [ ] **drafting**: 验证规则已执行，ADR 决策已提取
+- [ ] **redteam**: 安全类验证规则已执行
+- [ ] **qa**: 质量门禁分数已记录，所有 error 级规则已通过
+- [ ] **delivery**: 知识引用报告已生成，ADR 已归档，度量已记录
+- [ ] **deployment**: 部署度量已记录，统一治理报告已生成
+
+### 9.3 交付前确认
+
+- [ ] 统一治理报告 (`output/governance-report.json`) 状态为 passed
+- [ ] 知识覆盖率达到配置阈值（默认 0.6）
+- [ ] 所有 error 级验证规则通过
+- [ ] ADR 文档已包含在交付证据包中
+- [ ] DORA 指标已更新
+
+### 9.4 常见问题排查
+
+| 问题 | 检查项 | 解决方案 |
+|------|--------|----------|
+| 验证规则未执行 | `validation_rules.enabled` | 检查 `umadev.yaml` 配置 |
+| 知识覆盖率为 0 | Knowledge Tracker 启动 | 确认 `knowledge/` 目录非空 |
+| ADR 生成为空 | 架构配置 | 确认 `umadev.yaml` 有 frontend/backend/database 配置 |
+| 度量数据缺失 | metrics 目录权限 | 确认 `output/metrics/` 目录可写 |
+| 自定义规则不生效 | YAML 语法 | 使用 `umadev governance rules validate` 检查 |
+
+### 9.5 治理能力启用矩阵
+
+| 治理能力 | 默认状态 | 推荐级别 | 企业级别 |
+|----------|----------|----------|----------|
+| Validation Rules | 启用 (warning) | 启用 (error) | 启用 (error + fail_on_warning) |
+| Knowledge Tracker | 启用 | 启用 + 覆盖率检查 | 启用 + min_coverage: 0.8 |
+| Prompt Templates | 启用 | 启用 + semver | 启用 + 审批流程 |
+| ADR Generator | 启用 | 启用 | 启用 + 强制归档 |
+| Pipeline Metrics | 启用 | 启用 + 周报 | 启用 + 外部 BI 集成 |
+
+---
+
+## 10. 参考资料
+
+- [DORA Metrics](https://dora.dev/) — DevOps Research and Assessment
+- [MADR](https://adr.github.io/madr/) — Markdown Architectural Decision Records
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/) — Web 应用安全风险
+- UmaDev 源码: `umadev/orchestrator/governance.py`
+- UmaDev 配置: `umadev.yaml`
+- UmaDev 自定义规则示例: `.umadev/rules/custom_rules.yaml`

package/00-governance/knowledge-map.md

@@ -0,0 +1,39 @@
+---
+id: knowledge-map
+title: knowledge-map
+domain: 00-governance
+category: knowledge-map.md
+difficulty: intermediate
+tags: [00-governance, knowledge, map]
+quality_score: 70
+last_updated: 2026-06-15
+---
+# 开发：Excellent（11964948@qq.com）
+
+## 知识库地图（全环节）
+
+### 1. 目标
+- 建立可持续演进的项目知识系统，减少“只靠人记忆”带来的交付风险。
+- 让需求增强、文档生成、评审与上线决策都能引用统一知识源。
+
+### 2. 生命周期映射
+- 战略与机会：`product/`
+- 设计与体验：`design/`
+- 架构与实现：`architecture/`、`development/`
+- 质量与安全：`testing/`、`security/`
+- 交付与运维：`cicd/`、`operations/`
+- 数据与增长：`data/`
+- 事故与复盘：`incident/`
+- AI与自动化：`ai/`
+
+### 3. 强关联关系
+- `product` 决定 `architecture` 的边界与非功能指标。
+- `architecture` 约束 `development` 的实现模式。
+- `testing` 与 `security` 共同定义 `cicd` 的门禁。
+- `operations` 的监控与事故数据反哺 `product` 与 `architecture`。
+- `ai` 的安全与评测要求同时受 `security/testing/operations` 约束。
+
+### 4. 版本与审查
+- P0条目：月度审查。
+- P1条目：季度审查。
+- P2条目：半年度审查。

package/00-governance/maintenance-policy.md

@@ -0,0 +1,76 @@
+---
+id: maintenance-policy
+title: 知识库维护政策
+domain: 00-governance
+category: 01-standards
+difficulty: intermediate
+tags: [00-governance, maintenance, policy, lifecycle, quality]
+quality_score: 88
+last_updated: 2026-06-16
+---
+
+# 知识库维护政策
+
+## 所有权与责任矩阵
+
+| 角色 | 职责 | 频率 |
+|---|---|---|
+| **知识库所有者** (platform-team) | 审批新增/删除域，维护 00-governance/ 规范 | 季度 |
+| **域维护者** (per-domain) | 审批域内文件变更，保证质量分 ≥ 70 | 双周 |
+| **贡献者** (any agent/user) | 提交新文件或修订，附完整 front-matter | 随时 |
+
+## 文件生命周期
+
+### 新增
+1. 文件必须包含完整 front-matter（`id`, `title`, `domain`, `tags`, `quality_score`, `difficulty`）。
+2. 文件字数 ≥ 200 词（CJK 按 1.5× 折算）；低于阈值的标记 `status: draft`。
+3. 新增域需经知识库所有者审批，且初始至少 3 个文件。
+4. `quality_score` 初值 = 70，贡献者可自行调整。
+
+### 修订
+1. 修订后必须更新 `last_updated` 日期。
+2. 内容变更超过 30% 时 `version` 字段 +1。
+3. 修订不得删除已有 H2 章节（只能标记 deprecated）。
+
+### 归档与删除
+1. 连续 2 个季度无修订且无检索命中的文件 → 标记 `status: archived`。
+2. 归档文件移入 `<domain>/99-archived/` 子目录，不参与默认检索。
+3. 仅知识库所有者可执行物理删除，需在变更记录中写明原因。
+
+## 质量门禁
+
+- 每个文件的 `quality_score` 必须 ≥ 50；低于 50 的文件不进入 BM25 索引。
+- 每季度全库扫描：`quality_score < 60` 的文件通知域维护者复审。
+- front-matter 完整性检查：`tags` 非空、`domain` 与路径一致、`quality_score` 为整数。
+
+## 检索权重规则
+
+- `quality_score` 作为 BM25 分数的弱加权：`score × (1 + quality/200)`。
+- `difficulty = advanced` 的文件在同分时优先（企业级场景更需深度知识）。
+- `.umadev/learned/` 下的经验文件 `quality_score` 固定为 80（项目专属高价值）。
+
+## 失效治理
+
+- 每周检测失效链接并替换或移除。
+- 每月清理重复条目与过期策略。
+- 每季度做知识结构重组，保持检索可读性。
+- 索引缓存（`bm25.bin` / `vectors.bin`）通过 content-hash 自动失效，无需手动清除。
+
+## front-matter 兼容性
+
+- schema 变更必须向后兼容（新字段 `#[serde(default)]`）。
+- 旧格式文件（无 `quality_score`）通过 `cargo run --example backfill-frontmatter -- --fix` 补齐。
+- 三种 front-matter 历史格式（legacy/numbered/complete）均被 chunker 兼容解析。
+
+## 升级流程
+
+1. 在 `docs/plans/` 创建升级方案文档。
+2. 知识库所有者审批。
+3. 执行变更（新增/修订/归档）。
+4. 运行 `cargo test -p umadev-knowledge` 验证索引构建。
+5. 更新 `docs/ARCHITECTURE.md` 如有结构性变更。
+
+## 变更记录
+
+每次更新追加"变更摘要"，说明原因、影响范围、回归检查结果。变更记录写入
+`00-governance/changelog.md`（按需创建）。