apecloud · weicao · May 3, 2026 · May 3, 2026
diff --git a/docs/addon-controller-crash-resilience-guide.md b/docs/addon-controller-crash-resilience-guide.md
@@ -1,5 +1,11 @@
 # Addon Controller Crash Resilience 指南
 
+> **Audience**: addon dev / test / TL，需要验证 addon 在 KubeBlocks 控制器中段失效后的恢复语义
+> **Status**: stable
+> **Applies to**: any KB addon（控制层 crash 是 K8s 通用属性，不绑定单引擎）
+> **Applies to KB version**: any（控制器 crash-recover 语义在 KB 各版本下行为一致；本文方法论 version-agnostic）
+> **Affected by version skew**: 不受 KB 版本影响 — 控制器 crash 后从 CR desired state 恢复是 K8s controller 通用契约
+
 本文面向 Addon 开发与测试工程师，聚焦一个被频繁默认而很少被显式验证的属性：**当 KubeBlocks 控制器在一个 Ops 进行到一半时被 crash / SIGKILL，重新拉起后，相关 OpsRequest 与 Cluster 是否能继续推进到正确终态。**
 
 正文只写通用方法论，不绑定某一个引擎或某一类 Ops。引擎相关的现场和案例放在附录。

diff --git a/docs/addon-design-contract-review-during-xp-guide.md b/docs/addon-design-contract-review-during-xp-guide.md
@@ -1,5 +1,11 @@
 # Addon Design-Contract Review During XP 指南
 
+> **Audience**: addon dev / test 工程师（XP 模式下两个角色同一人）+ pair-programming reviewer
+> **Status**: stable
+> **Applies to**: any KB addon（设计契约级 review 方法论，不绑定单引擎或单 ops 类型）
+> **Applies to KB version**: any（review 模式与 KB 版本解耦；引擎特化 8 类 blocker 实证在文末附录）
+> **Affected by version skew**: 不受 KB 版本影响 — review checklist 跨 KB 版本通用
+
 本文面向 Addon 开发与测试工程师（XP 模式下他们是同一个人），聚焦一个常被默认但很少显式验证的属性：**review 阶段必须做"设计契约级 challenge"，不只是 syntax / lint / 测试通过的检查；这种 review 抓到的问题会比 e2e 早一个数量级**。
 
 正文写通用方法论，引擎相关的实证（具体 8 类 blocker 的代码现场）在文末附录。

diff --git a/docs/addon-pvc-rebind-via-workload-intent-guide.md b/docs/addon-pvc-rebind-via-workload-intent-guide.md
@@ -1,5 +1,11 @@
 # Addon PVC Rebind via Workload Intent 指南
 
+> **Audience**: addon dev / test / TL，需要设计或排查 OpsRequest 跨控制器 PVC 改绑（rebuild / restore-into-place / PV migration）路径
+> **Status**: stable
+> **Applies to**: any KB addon（跨 OpsRequest 控制器 + Workload 控制器 + 动态 provisioner 的所有权交接是 KubeBlocks 通用模式）
+> **Applies to KB version**: KB 1.0.x / 1.1.x / main（Workload Intent annotation 模式与具体 KB 版本解耦；引擎特化样本在 commit `a2ffaed` 后续 case 附录）
+> **Affected by version skew**: 不受 KB 版本影响 — Workload CR annotation contract 跨版本一致
+
 本文面向 Addon 开发与测试工程师，聚焦一个在 OpsRequest 控制器和 Workload 控制器同时存在的体系里几乎一定会遇到的问题：**当某个 OpsRequest 想把同一个 PVC 名字下的存储从一块旧 PV 改绑到一块预先准备好的新 PV，而 Workload 控制器又会按模板自动重建丢失的 PVC，两边会抢同一个 PVC 名字的所有权。**
 
 正文写通用方法论，不绑定某一个引擎、不绑定某一类 Ops；引擎相关的现场、命令、案例放在附录。

diff --git a/docs/addon-ship-readiness-multi-phase-validation-guide.md b/docs/addon-ship-readiness-multi-phase-validation-guide.md
@@ -1,5 +1,11 @@
 # Addon Ship-Readiness 多阶段验证矩阵指南
 
+> **Audience**: addon TL / test 工程师，需要决定 addon 何时可以发布
+> **Status**: stable
+> **Applies to**: any KB addon（ship-readiness gate 是引擎无关的发布决策方法论）
+> **Applies to KB version**: any（验证矩阵框架不依赖具体 KB 版本；引擎特化 N 计数 / flake 阈值由 owner 在案例附录补）
+> **Affected by version skew**: 不受 KB 版本影响 — 三段矩阵 + Wilson CI + 二段 ship 判定与 KB 版本演化解耦
+
 本文面向 Addon 技术负责人 / 测试工程师，回答一个不太好定义的问题：**一个 addon 在什么时候能被标记为可以发布？** 不是"测试都跑过一次"，也不是"chaos 跑了一晚上"，而是有一个分阶段、可累积证据、可量化 flake 复现率的验证矩阵。
 
 正文是引擎无关的方法论，引擎相关结果放在案例附录。