docs: clarify gitops sync waves

gitops-app-onboarding/SKILL.md

@@ -278,19 +278,31 @@ Chart 必须反映应用的真实运行架构。
 - annotation 键必须写成 `argocd.argoproj.io/sync-wave`，不要写成 `rgocd.argoproj.io/sync-wave` 或其他拼写
 - wave 值使用字符串，例如 `"-20"`、`"0"`、`"10"`
 - 低 wave 先同步，高 wave 后同步；不要把依赖方和被依赖方放在同一个 wave
+- `releases/<app>/manifests/` 下的资源也必须参与 wave 设计；不要只给 Helm Chart 模板里的资源排序
+- 被 Job、Deployment、StatefulSet 或 Pod 通过 `envFrom`、`secretKeyRef`、`configMapKeyRef`、volume、`imagePullSecrets` 消费的 Secret / ConfigMap，wave 必须早于消费它们的 workload
+- `registry-pull-secret`、`platform-shared-secrets` 等平台托管共享资源的 wave 已固定为 `"-1"`；不要修改它们，应用资源应围绕这个锚点排序
+- `manifests/db-secret.yaml` 如果存在，必须早于所有读取 `databaseSecret` / `<app>-db` 的 migrate Job 和业务 workload；推荐使用 `"0"`
+- 应用私有 Secret、应用私有 ConfigMap 必须早于所有会消费它们的 workload；推荐使用 `"0"`
 - 只有确实存在跨资源启动顺序要求时才加 sync-wave，不要给所有资源机械添加 annotation
 
 推荐顺序：
 
-- `-30`：ServiceAccount、RBAC、基础 Secret、基础 ConfigMap
-- `-20`：PVC / `volumeClaimTemplates` 所依赖的存储前置资源、应用私有 Secret、应用私有 ConfigMap
-- `-10`：应用自带的私有基础设施，例如 Neo4j、向量库、内部依赖服务的 StatefulSet / Deployment
-- `-5`：内部依赖的 Service，尤其是会被后续 nginx upstream 或应用启动配置引用的服务名
-- `0`：后端、worker、API 等核心业务 Deployment / StatefulSet
-- `5`：核心业务 Service
-- `10`：nginx / frontend 入口 Deployment，以及对外 `NodePort` Service
+- `-1`：平台托管共享资源，例如 `registry-pull-secret`、`platform-shared-secrets`、平台共享 ConfigMap
+- `0`：应用自有前置资源，例如 ServiceAccount、RBAC、`manifests/db-secret.yaml`、应用私有 Secret、应用私有 ConfigMap、PVC / `volumeClaimTemplates` 所依赖的存储前置资源
+- `10`：migrate Job、应用自带的私有基础设施，例如 Neo4j、向量库、内部依赖服务的 StatefulSet / Deployment
+- `15`：内部依赖的 Service，尤其是会被后续 nginx upstream 或应用启动配置引用的服务名
+- `20`：后端、worker、API 等核心业务 Deployment / StatefulSet
+- `25`：核心业务 Service
+- `30`：nginx / frontend 入口 Deployment，以及对外 `NodePort` Service
 
-如果 nginx 配置在容器启动时解析 upstream，必须保证 upstream 对应 Service 的 wave 早于 nginx Deployment；如果应用启动依赖 Secret / ConfigMap / PVC，必须保证这些资源的 wave 早于消费它们的 workload。
+如果 nginx 配置在容器启动时解析 upstream，必须保证 upstream 对应 Service 的 wave 早于 nginx Deployment；如果应用启动依赖 Secret / ConfigMap / PVC / imagePullSecret，必须保证这些资源的 wave 早于消费它们的 workload。尤其注意平台共享资源已经在 `"-1"`，应用自有 secret/config 应从 `"0"` 开始，migrate Job 这类消费者必须排在它们之后，例如 `"10"`，不能把消费者放到 `"-10"` 或同一个 wave 里。
+
+生成或修复 release manifests 时，逐项核对：
+
+- `releases/<app>/manifests/db-secret.yaml` 的 wave 早于 Chart 中所有引用该 secret 的 Job / Deployment / StatefulSet
+- `releases/<app>/manifests/secret.yaml` 的 wave 早于 Chart 中所有引用该 secret 的 workload
+- `registry-pull-secret` 在目标 namespace 存在，且 wave 早于所有使用私有镜像的 workload
+- 共享 secret / config 如果由 release manifests 或 shared manifests 同步，也早于所有消费者
 
 如果应用依赖平台 shared 之外的私有服务，必须明确表达依赖来源：
 
@@ -500,6 +512,9 @@ Chart 必须反映应用的真实运行架构。
 - Neo4j 一类自带依赖的启动环境变量不依赖 `$(OTHER_ENV)` 展开
 - 如果应用包含需要持久化数据的服务，对应 PVC / `volumeClaimTemplates` 已显式设置 `storageClassName: longhorn`
 - 如果资源存在启动顺序依赖，`argocd.argoproj.io/sync-wave` 拼写正确，wave 顺序符合依赖方向
+- `releases/<app>/manifests/db-secret.yaml`、`secret.yaml`、pull secret、shared secret/config 的 wave 早于所有引用它们的 migrate Job 和业务 workload
+- `registry-pull-secret`、`platform-shared-secrets` 等平台托管资源保持平台约定的 `"-1"`，应用自有前置资源围绕它排序，不要改平台资源 wave
+- migrate Job 不要设置成负 wave；它依赖的应用自有 Secret / ConfigMap / DB secret 通常在 `"0"`，migrate Job 应排在更高 wave，例如 `"10"`
 - 如果检测到的私有 Git 依赖中包含 `git.in.chaitin.net/ai/baizhiyun/opensdk`，缺少必填百智云私有配置时交互停在当前项继续索取
 
 ## 最终输出
@@ -527,3 +542,5 @@ Chart 必须反映应用的真实运行架构。
 - `update-gitops-repo` 没有依赖 `package-chart`，GitOps 仓库先于 Chart 推送被更新
 - 在 `.gitlab-ci.yml` 中用 Python heredoc 临时改 `Chart.yaml`、release values 或 `application.yaml`
 - `argocd.argoproj.io/sync-wave` 拼错为 `rgocd.argoproj.io/sync-wave`，或把依赖方放在被依赖资源之前
+- 只给 Chart 模板资源设计 wave，却遗漏 `releases/<app>/manifests/db-secret.yaml`、`secret.yaml`、pull secret 等 release manifests，导致 migrate Job 先于 Secret 执行
+- 不顾平台约定把 `registry-pull-secret`、`platform-shared-secrets` 等平台托管资源改成其他 wave；正确做法是保持它们在 `"-1"`，应用资源围绕 `"-1"` 排序