From 67922c589a68fa353b97fae2d27732452bdc90dd Mon Sep 17 00:00:00 2001
From: Your Name <your.email@example.com>
Date: Wed, 6 May 2026 12:46:22 +0800
Subject: [PATCH] docs(ci): document protected status contexts

---
 .gitea/workflows/ci.yml  | 5 +++++
 .github/workflows/ci.yml | 5 +++++
 CONTRIBUTING.md          | 1 +
 README.md                | 2 ++
 4 files changed, 13 insertions(+)

diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index 2491fc3..3ace7a5 100644
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -1,3 +1,7 @@
+# Keep workflow name stable.
+# Branch protection and external CI references rely on:
+# - CI / verify (push)
+# - CI / verify (pull_request)
 name: CI
 
 on:
@@ -9,6 +13,7 @@ on:
 
 jobs:
   verify:
+    # Keep job id stable. Renaming it changes the status context.
     runs-on: ubuntu-latest
     env:
       WORKSPACE_DIR: ${{ github.workspace }}/repo
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ee6a13a..4bb8b68 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,3 +1,7 @@
+# Keep workflow name stable.
+# Branch protection and external CI references rely on:
+# - CI / verify (push)
+# - CI / verify (pull_request)
 name: CI
 
 on:
@@ -12,6 +16,7 @@ permissions:
 
 jobs:
   verify:
+    # Keep job id stable. Renaming it changes the status context.
     runs-on: ubuntu-latest
     timeout-minutes: 20
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 33be0c7..9594077 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -58,6 +58,7 @@ chore(scope): summary
 - 新接口是否有明确的错误码和测试
 - 平台适配是否仍然只停留在边缘层
 - callback / outbox / dead letter 是否可追踪、可重放
+- `.github/workflows/ci.yml` 与 `.gitea/workflows/ci.yml` 的 `name: CI` 和 `jobs.verify` 是否保持稳定，避免破坏受保护状态上下文
 
 ## 参考文档
 
diff --git a/README.md b/README.md
index aaca3d8..0bdf8ad 100644
--- a/README.md
+++ b/README.md
@@ -130,6 +130,8 @@ go vet ./...
   GitHub 执行 `go test ./... -count=1`、`go test -race ./...`、`go vet ./...`、Gate 脚本语法检查；
   Gitea/TKSea 因共享测试库约束，执行 `go test ./... -count=1 -p 1`、`go test -race ./... -p 1`、`go vet ./...`、Gate 脚本语法检查
 - GitHub 使用 [`.github/workflows/ci.yml`](.github/workflows/ci.yml)，Gitea/TKSea 使用 [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml)
+- `workflow` 名称和 `verify` job 名称属于受保护契约。当前分支保护依赖这两个状态上下文：
+  `CI / verify (push)`、`CI / verify (pull_request)`；不要随意改名
 - 本地默认共享 PostgreSQL 测试库，所以本地验证命令统一使用 `-p 1` 串行执行，避免跨包并发污染测试表
 - 变更配置契约时，必须同步更新：
   - `docs/CONFIG_CONTRACT_BASELINE.md`