docs: add runtime contract preflight guide (3-layer chart-vs-runtime drift)

docs/SKILL-INDEX.md

@@ -53,6 +53,7 @@
 - [`addon-k3d-backup-restore-prereqs-guide.md`](addon-k3d-backup-restore-prereqs-guide.md) — k3d 跑 Backup/Restore 的两层前置：装 VolumeSnapshot CRD + 建默认 BackupRepo
 - [`addon-idc-image-registry-mirror-guide.md`](addon-idc-image-registry-mirror-guide.md) — IDC vcluster 镜像供给的三档决策（mirror 主路径 / ACR 直拉 / sideload 兜底）+ chart audit 反 ghcr.io / docker.io 主依赖 + vcluster 内 chaos-mesh 双层 syncer 注入；含 6 line × 3 IDC 行 ground-truth cross-engine reuse 表
 - [`addon-multi-ns-registry-scan-preflight-guide.md`](addon-multi-ns-registry-scan-preflight-guide.md) — *(also relevant in: 写新 smoke / chaos 测试)* 多 ns / 多 topology 测试启动前 audit live `ComponentVersion` + `ParametersDefinition.toolsSetup.toolConfigs[].image` 的 image source；verified scope vs scan-only future-gate 二分
+- [`addon-runtime-contract-preflight-guide.md`](addon-runtime-contract-preflight-guide.md) — chart spec 与 runtime 实际契约的 3 个对齐 surface preflight：Layer 1 (chart spec 字段被 KB CRD schema reject, install-time fail) / Layer 2 (vcluster substrate bootstrap precondition, CoreDNS image pull fail 但 control plane 报 Running) / Layer 5 (chart spec 没 declare addon 自身 runtime env, ActionSet `spec.env` declare 与 backup script 引用差集 → silent-empty + cryptic surface error 如 ORA-12154)。Non-contiguous Layer 编号（0/3/4 reserved）+ 4-step preflight + 4-pillar 跨引擎表 + Layer 1/2/5 mermaid 决策树 + Archetype "chart-spec-doesnt-declare-runtime-requirement"。Oracle line W7 grounded (idc4 19c standalone 553MB 2m32s + 12c standalone 628MB 1m58s 双 minor-version confirm) + MariaDB line idc bastion view (PR #54 §1 §5 mirror family + 11:16-12:55 syncer 实战) cross-line co-author。与 [`addon-kb-schema-version-preflight-guide.md`](addon-kb-schema-version-preflight-guide.md)（schema dimension）+ [`addon-test-script-preflight-guide.md`](addon-test-script-preflight-guide.md)（shared client state dimension）+ [`addon-vcluster-kb-install-preflight-guide.md`](addon-vcluster-kb-install-preflight-guide.md)（bootstrap harness dimension）+ [`addon-multi-ns-registry-scan-preflight-guide.md`](addon-multi-ns-registry-scan-preflight-guide.md)（测试 scope dimension）共同构成 preflight family 5 doc，scope 严格不重叠
 - [`addon-idc-vcluster-migration-checklist-guide.md`](addon-idc-vcluster-migration-checklist-guide.md) — addon 测试环境从本地 k3d / 单租户 idc 迁到 IDC 共享 k8s + 每线 vcluster 时的迁移 checklist：per-cluster baseline 维度、4 条架构 invariant（runner-on-host / vcluster API 内通主路 NodePort 兜底 / 控制器全部 in-vcluster / 显式 KUBECONFIG 锁）、13 条已观察反模式（NodePort SAN / HTTPS_PROXY / libc / 跨 arch / default-class 不 sync / data-protection 缺装 / VolumeSnapshot CRD 缺 / chart 全局 nodeSelector 经 CM_NODE_SELECTOR 泄漏 / IDC LB 无 EXTERNAL-IP / pod IP cap 探测 / chaos 跑赢 CNI 回收 / helm hook 镜像不存在 / 缺装组件枚举），+ "环境 fault before engine fault" 5 项 cross-cutting checklist
 - [`addon-vanilla-vcluster-bootstrap-guide.md`](addon-vanilla-vcluster-bootstrap-guide.md) — 在 IDC host k8s 上创建 vanilla（OSS 0.19.x，非 Loft 企业版）vcluster 的完整 bootstrap 步骤：default StorageClass / node 资源 / ghcr.io mirror / kubeconfig 隔离 4 项前置 + helm install + kubeconfig (port-forward vs NodePort) + 验证 + 8 个跨线 Blocker 汇总
 
@@ -128,6 +129,7 @@
 - [`docs/addon-ship-readiness-multi-phase-validation-guide.md`](addon-ship-readiness-multi-phase-validation-guide.md) — addon 何时算可以 ship 的三段矩阵（baseline / chaos × N / regression × N），累积 N、Wilson 95% CI、ship 阈值表（数据丢失 0% / 服务不可用 5% / transient 30%）、二段判定（产品 fail = 0 + caveat 全 document）+ 5 个常见误判
 - [`docs/addon-github-submission-discipline-guide.md`](addon-github-submission-discipline-guide.md) — 多 agent 协作 + GitHub 公开仓库的边界纪律：(1) AI provenance trailer（`Co-Authored-By: Claude` / `🤖 Generated with` / `noreply@anthropic.com`）不外漏的硬规则与兜底命令链（heredoc + `git commit --amend -m "$(... | sed)"` strip / push 前 grep 自检）；(2) 多 agent 并发推同一 PR branch 的 cascade 事故响应 playbook（force-with-lease lemma：lease 锚 last-fetched remote tip 不防 fetch 后并发 push / 双向 `git log --oneline` ritual / dropped-commit owner self-recover / single-owner-execute 收口）。5 条 doctrine（A force-with-lease / B per-commit grep / C cascade single-owner-execute / D forensic 自查 / E content-delta verify）+ §5 cross-cutting rules（forensic self-review / Doctrine E shorthand / evidence-post obligation / 递归 self-application）
 - [`docs/addon-soak-test-result-classification-guide.md`](addon-soak-test-result-classification-guide.md) — 长跑型测试（24h+ soak / chaos / fault-injection）出结果之后的结果分类方法论。**核心 framing**：fault total / PASS-FAIL 计数无法回答"是否 ACCEPTED"，必须把每条 fault 注入按"哪一层先失败"落到 4-state schema：(1) `invariant-break`（不变量破坏 → ROLLBACK）/ (2) `product-path-failure`（产品恢复路径失败）/ (3) `harness-race`（测试工具时序竞争）/ (4) `external-environmental-cascade`（外部环境级联）。**判据**：Q1（bad_ack > 0）→ Q2（cluster 终态）→ Q3（OpsRequest Failed + N≥2 自验证）→ Q4（duration 超 mean+3σ + 外部事件关联 + 对照样本）→ product-pass（mermaid 流程图）。**N≥2 自验证最小证据门槛**：harness-race 需同类 Succeed 对照、cascade 需 baseline ±1σ 对照样本；单 sample 不能下"非产品"结论。**ACCEPTED 判据**：`invariant-break = 0 AND product-path-failure = 0`，harness-race / cascade 不阻塞但触发对应修复 ticket。grounded N=3 CH30 harness-race 对照（fault-026 vs 029/033）+ N=2 CH20 cascade negative-control（fault-028 21min outlier vs 031 95s 1σ 内）+ AG quorum non-sticky 3-transition 行为附注。与 [`addon-test-acceptance-and-first-blocker-guide.md`](addon-test-acceptance-and-first-blocker-guide.md) 单次 fail first-blocker 分层方法论形成互补对子（前者聚合维度，后者单次维度）
+- [`docs/addon-runtime-contract-preflight-guide.md`](addon-runtime-contract-preflight-guide.md) — chart install schema 全过 + smoke 全 PASS 但 runtime cryptic 报错的隐藏失败模式预检方法论。聚焦三个对齐 surface：(1) Layer 0/1 chart spec 字段 → KB CRD schema 兼容性（image / chart / CRD 三层）；(2) Layer 2 vcluster substrate bootstrap precondition（外网拉镜像不通时的离线方案）；(3) Layer 5 ActionSet env contract drift（chart 没 declare runtime env，runtime 拿到 empty → 下游 cryptic 报错）。包含 4-step preflight 流程 + 跨引擎 4-pillar 口径同步表 + 决策树 + 4 case appendix（Oracle W7 ActionSet env / vcluster CoreDNS ImagePullBackOff / chart 跟 KB main isExclusive / MariaDB mirror family）。与 [`addon-kb-schema-version-preflight-guide.md`](addon-kb-schema-version-preflight-guide.md) 是 schema dimension vs runtime contract dimension 正交对子；与 [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md) 是 preflight (本文) vs diagnosis (后者) lifecycle 互补；与 [`addon-soak-test-result-classification-guide.md`](addon-soak-test-result-classification-guide.md) 是 lifecycle preflight before vs classification after 互补
 
 ## 案例材料