feat: 建立安全的合并与分支清理治理

AGENTS.md

@@ -19,4 +19,4 @@
 
 - 优先识别会造成错误放行、错误阻断、权限扩大、secret 暴露、供应链漂移或发布/回滚证据失真的具体问题，并核对新增公共 MUST 是否确实跨项目通用。
 - 审计器变更必须同时具有能复现旧缺口的失败 fixture 和保持合法项目通过的正例；只增加字符串匹配而不能证明约束时应指出误报或漏报路径。
-- 修改 Action 或公共规则时，核对模板、审计器已知映射、契约和 fixture 是否同步；不重复报告 lint、格式化或纯风格问题，不要求与当前风险无关的重构。
+- 修改 Action 或公共规则时，核对模板、审计器已知映射、契约和 fixture 是否同步；不重复报告 lint、格式化或纯风格问题，不要求与当前风险无关的重构。官方 Review 当前不是 required check，且 GitHub 对有写权限者推送新提交不保证自动关闭 Auto-merge；v1 暂不允许对单个 PR 开启 Auto-merge，只在 Review 当前 HEAD、全部 review thread 已解决后人工合并。

MAINTENANCE.md

@@ -24,13 +24,14 @@
 
 1. 在独立 worktree 中复制 `templates/AGENTS.md`，替换占位符并补齐项目内部规则；项目规则不得降低公共 MUST，根文件必须保留精确 `## Code Review Rules` 标题。
 2. 在官方 GitHub/Codex 设置中启用 Code Review 与 `Automatic reviews`，并用真实 PR 验证自动审查；未触发或需要重审时使用 `@codex review`。
-3. 复制并按项目实际情况改造 `templates/` 下的 PR、release workflow、`release-safety.yml` 与 `release-safety-contract.sh`；把后两者分别安装为 `.github/release-safety.yml` 与 `.github/scripts/release-safety-contract.sh`，保持 wrapper 的 Git mode 为 `100755`，并映射项目真实 job/step 拓扑。
-4. 通过真实 PR 证明 `PR container validation` 成功，随后原子迁移 master required check。
-5. 通过一次 master 发布证明 Environment-only secret、旧运行态捕获、候选镜像身份、容器内 smoke、成功后清理和 `DEPLOY_TARGET_SHA` 发布证据。
-6. 将 `owner/repo` 追加到 `repositories.txt`。
-7. 将仓库名追加到中央 `.github/workflows/baseline-drift-audit.yml` 的 `repositories` 显式列表；测试会要求该列表与清单顺序一致。
-8. 把只读 GitHub App `Engineering Baseline Auditor` 的安装范围扩展到新仓库；纳管项目不得保存 App 私钥或个人访问令牌。
-9. 运行 fixture 测试，并在基线仓库人工触发中央 live 审计；两者都成功后才算纳入基线。
+3. 保持 Auto-merge 关闭；官方 Review 尚非 required check 时不得为单个 PR 开启 Auto-merge。只有仓库仅使用临时 PR head 分支，或所有长期 head 分支受保护时，才启用合并后自动删除远端分支。
+4. 复制并按项目实际情况改造 `templates/` 下的 PR、release workflow、`release-safety.yml` 与 `release-safety-contract.sh`；把后两者分别安装为 `.github/release-safety.yml` 与 `.github/scripts/release-safety-contract.sh`，保持 wrapper 的 Git mode 为 `100755`，并映射项目真实 job/step 拓扑。
+5. 通过真实 PR 证明 `PR container validation` 成功，随后原子迁移 master required check。
+6. 通过一次 master 发布证明 Environment-only secret、旧运行态捕获、候选镜像身份、容器内 smoke、成功后清理和 `DEPLOY_TARGET_SHA` 发布证据。
+7. 将 `owner/repo` 追加到 `repositories.txt`。
+8. 将仓库名追加到中央 `.github/workflows/baseline-drift-audit.yml` 的 `repositories` 显式列表；测试会要求该列表与清单顺序一致。
+9. 把只读 GitHub App `Engineering Baseline Auditor` 的安装范围扩展到新仓库；纳管项目不得保存 App 私钥或个人访问令牌。
+10. 运行 fixture 测试，并在基线仓库人工触发中央 live 审计；两者都成功后才算纳入基线。
 
 固定 wrapper 内部可以复用既有语言或容器测试；`PR container validation` job 名称必须全局唯一、无 `if`、无 `needs`、无有效 `continue-on-error`，workflow/job 不得覆盖默认 `shell` 或 `working-directory`。manifest 映射的主 PR targeted step 必须以单行 `run` 精确等于 wrapper 路径，不能附加参数、前后命令、`;`、管道或 `||`，也不能声明 `if`、`continue-on-error`、`shell`、`working-directory`，或把 ID 挂到 checkout、`echo`、`test -f` 与不相关的完整构建步骤。
 
@@ -58,6 +59,15 @@ prepare 存在时，publish、migration 与 deploy 必须使用 `needs.<prepare>
 - 官方设置和审查行为通过真实 PR 验收；中央审计只检查根 `AGENTS.md` 是普通文件，且固定 `markdown-it-py==3.0.0` CommonMark parser 产生源码行精确等于 `## Code Review Rules` 的真实 h2。不得恢复手写 Markdown 状态机，也不抓取页面或调用私有接口。
 - 官方功能演进时先更新接入说明和精简规则；若官方补齐缺口，优先删除临时流程，不维护平行实现。
 
+## Auto-merge 维护
+
+- GitHub 只保证无写权限者推送新提交时关闭 Auto-merge；有写权限者推送后不保证自动关闭。官方 Review 当前不是 required check，因此 v1 暂不允许仓库或单个 PR 开启 Auto-merge。
+- 不建立 HEAD 监听器、自动合并 Bot、Action 或定时任务来补这个能力缺口；未来等官方 Review 可成为当前 HEAD required gate，或 GitHub 保证任意新提交都会撤销 Auto-merge 后再评估。
+- 人工合并前确认官方 Review 当前 HEAD、全部 review thread 已解决、required checks 成功且风险已分类；新提交必须重新 Review。
+- Dependabot PR 不能只凭 CI 绿灯自动合并；运行时依赖、跨大版本和会触发生产发布的仓库必须另做兼容性与发布授权判断。
+- 分支自动删除不是公共强制项。只有仓库仅使用临时 PR head 分支，或所有长期 head 分支受保护时，才启用 GitHub 的合并后自动删除；存在未保护且需要复用的长期 head 分支时必须关闭。
+- 本地 worktree/分支只在已合并、干净、没有独有提交且相关发布验收完成后删除。
+
 ## Action 升级
 
 - 只接受上游官方 release 对应的完整 40 位 commit SHA。

README.md

@@ -11,13 +11,14 @@
 1. 从独立 Git worktree 创建变更分支，避免污染长期开发目录。
 2. 复制 `templates/AGENTS.md` 到项目根目录，替换全部 `PROJECT_REPLACE` 项并补齐项目内部规则，保留精确标题 `## Code Review Rules`。
 3. 在官方 GitHub/Codex 设置中启用 Code Review 与 `Automatic reviews`；规则只决定审查重点，不负责触发，人工兜底使用 `@codex review`。
-4. 复制 `templates/pr-ci.yml`、`templates/release.yml`、`templates/release-safety.yml` 和 `templates/release-safety-contract.sh`；将后两份分别安装为 `.github/release-safety.yml` 与 `.github/scripts/release-safety-contract.sh`，保持 wrapper 为 `100755`，再替换所有 `PROJECT_REPLACE` 项。
-5. 在仓库内实现项目自己的 PR 验证、镜像发布、向前迁移、部署、自动恢复、容器内 smoke、成功后镜像清理和发布收尾脚本；由固定 wrapper 调用项目语言或容器内的可执行契约测试，并让 manifest 声明 wrapper 与 PR 稳定步骤 ID。
-6. 创建 `dev` Environment，把发布所需 secret 移入该 Environment；确认发布成功后清理 repository-scope secrets。
-7. 为 `master` 启用保护规则，要求 GitHub Actions 产生的 `PR container validation`，并保持 strict。
-8. 在真实 PR 上先让新检查通过，再原子替换旧 required check；不要先删除旧门禁。
-9. 合并后核对运行容器的 image ref、内容 ID 与 `DEPLOY_TARGET_SHA`，并执行容器内部 smoke。
-10. 使用只读审计检查规则漂移。
+4. 保持仓库 Auto-merge 关闭；官方 Review 尚非 required check 时不得对单个 PR 开启 Auto-merge。只有仓库仅使用临时 PR head 分支，或所有长期 head 分支受保护时，才启用合并后自动删除远端分支。
+5. 复制 `templates/pr-ci.yml`、`templates/release.yml`、`templates/release-safety.yml` 和 `templates/release-safety-contract.sh`；将后两份分别安装为 `.github/release-safety.yml` 与 `.github/scripts/release-safety-contract.sh`，保持 wrapper 为 `100755`，再替换所有 `PROJECT_REPLACE` 项。
+6. 在仓库内实现项目自己的 PR 验证、镜像发布、向前迁移、部署、自动恢复、容器内 smoke、成功后镜像清理和发布收尾脚本；由固定 wrapper 调用项目语言或容器内的可执行契约测试，并让 manifest 声明 wrapper 与 PR 稳定步骤 ID。
+7. 创建 `dev` Environment，把发布所需 secret 移入该 Environment；确认发布成功后清理 repository-scope secrets。
+8. 为 `master` 启用保护规则，要求 GitHub Actions 产生的 `PR container validation`，并保持 strict。
+9. 在真实 PR 上先让新检查通过，再原子替换旧 required check；不要先删除旧门禁。
+10. 合并后核对运行容器的 image ref、内容 ID 与 `DEPLOY_TARGET_SHA`，并执行容器内部 smoke。
+11. 使用只读审计检查规则漂移。
 
 完整 MUST 和项目扩展点见 [CI/CD 公共契约](contracts/ci-cd-baseline.md) 与 [官方 Codex Code Review 治理契约](contracts/codex-code-review.md)。
 
@@ -27,6 +28,14 @@
 
 根 `AGENTS.md` 的 `## Code Review Rules` 只告诉官方 Reviewer 应优先检查哪些项目风险，不能开启 Automatic reviews，也不能证明自动审查已经触发。v1 保持观察模式，不增加 required check，不改变现有 branch protection；官方设置通过真实 PR 验收，中央审计只验证仓库内可稳定读取的规则文件。完整边界见 [官方治理契约](contracts/codex-code-review.md)。
 
+## Auto-merge 与分支清理
+
+GitHub 只保证无写权限者推送新提交时关闭 Auto-merge；有写权限者推送后不保证自动关闭。由于官方 Review 当前不是 required check，纳管产品仓库在 v1 暂不允许开启 Auto-merge，也不为单个 PR 启用它。
+
+人工合并前必须确认官方 Review 当前 HEAD、全部 review thread 已解决且 required checks 成功；新提交必须重新 Review。Dependabot PR 不会自动合并；尤其是运行时依赖、跨大版本升级、构建行为变化，以及合并即触发生产发布的仓库，仍需兼容性判断和明确发布授权。
+
+分支自动删除不是公共强制项。只有仓库仅使用临时 PR head 分支，或所有长期 head 分支受保护时，才启用 GitHub 的合并后自动删除；存在未保护且需要复用的 `dev`、`release` 等长期 head 分支时必须关闭。本地 worktree 和分支始终只在确认已合并、工作区干净且没有独有提交后清理。
+
 ## 只读审计
 
 前置条件：已安装并登录 `gh`，安装 `Python 3`、`PyYAML>=6`、`markdown-it-py==3.0.0` 与 `mdurl==0.1.2`，当前身份对目标仓库至少具有读取 Actions、Environment、branch protection 和 secret 名称元数据的权限。
@@ -64,6 +73,7 @@
 - publish/deploy/finalize 的 master 边界、normal/rollback 分支、migration 跳过回滚和 rollback 允许式不能只靠 manifest 自我声明，中央会独立验证公共语义；
 - release 内未声明的特权 job、job 级写权限、动态分域 concurrency 和未锁定 digest 的 `docker://` Action；
 - `master` branch protection 和 required check。
+- 纳管产品仓库关闭 Auto-merge；分支自动删除按项目真实分支模型配置，不由公共审计强制。人工合并前的 Review/thread/风险分类仍由真实 PR 验收。
 
 中央审计明确不解释任意 shell 的控制流，也不尝试从注释、`echo`、here-doc、字符串或脚本名证明 ref/内容 ID 比对、容器内 smoke、回滚命令及实际 `DEPLOY_TARGET_SHA`。它也不抓取官方页面或私有接口来判断 Automatic reviews 设置和模型审查质量；这些事实分别由项目可执行契约测试、真实发布验收和真实 PR Review 负责。模板只是一种可复制 profile，`.github/release-safety.yml` 才是每个项目拓扑的声明式适配层。
 

contracts/ci-cd-baseline.md

@@ -60,6 +60,7 @@
 - MUST：required status checks 启用 strict，并要求 GitHub Actions app 产生的 `PR container validation`。
 - MUST：要求通过 Pull Request、对管理员执行保护、要求解决对话、禁止 force push、禁止删除 `master`。
 - MUST：迁移检查名时先让新检查在真实 PR 成功，再原子替换旧 required check。
+- MUST：官方 Review 尚不能作为当前 HEAD 的 required check 时，仓库关闭 Auto-merge。人工合并边界由官方 Review 治理契约决定，不能仅凭 CI 通过合并；分支自动删除按项目分支模型配置，不作为 CI/CD 公共门禁。
 - 项目扩展点：额外 required checks，例如 CodeQL、语言专项检查或合规扫描。
 
 ## 7. Environment 与 secret 边界

contracts/codex-code-review.md

@@ -29,13 +29,21 @@
 - MUST：v1 采用观察模式，官方 Review 不新增为 required status check，也不改变现有 `master` branch protection。
 - MUST：没有官方稳定状态接口和真实仓库验证前，不假设 Review 能映射为 GitHub required check、approval 或固定 check 名称。
 - MUST：Review 发现的问题按现有 PR 对话处理；是否阻塞合并由现有门禁和维护者判断，不增加平行状态机。
+- MUST：[GitHub 官方文档](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request)只保证无写权限者向已开启 Auto-merge 的 PR 推送时自动关闭；有写权限者推送新提交后不保证自动关闭，Auto-merge 可能继续保持开启。官方 Review 当前又不是 required check，因此 v1 暂不允许仓库或单个 PR 开启 Auto-merge。
+- MUST：不创建自研合并 Bot、Action、HEAD 监听器或平行状态机来补 GitHub/Codex 当前能力缺口。
+- MUST：合并后自动删除远端分支不是所有项目的公共强制项。只有仓库仅使用临时 PR head 分支，或所有长期 head 分支受保护时，才允许启用该设置；否则必须关闭，避免 GitHub 删除仍需复用的长期分支。
+- MUST：人工合并前必须确认官方 Review 当前 HEAD、全部 review thread 已解决、required checks 成功，且依赖或发布风险已分类。
+- MUST：PR 出现新提交后，旧 Review 不再作为当前 HEAD 的证据；必须重新 Review 并再次确认全部 review thread 已解决，才能人工合并。
+- MUST：Dependabot PR 不因 CI 通过而自动合并；运行时依赖、跨大版本升级、构建工具行为变化及会随合并触发生产发布的仓库，都必须先完成兼容性与发布授权判断。
+- 项目扩展点：未来只有在官方 Review 能成为与当前 HEAD 绑定的 required gate，或 GitHub 保证任意新提交都会撤销 Auto-merge 后，才重新评估启用原生 Auto-merge。
 
 ## 5. 审计与验收
 
 - MUST：中央只读审计检查根 `AGENTS.md` 是 Git tree 中的普通文件，并在 fenced code、HTML comment 与 raw HTML block 之外包含精确 `## Code Review Rules` 标题；缺失、symlink、非普通文件或缺少真实标题统一报告 `[CODE_REVIEW_RULES]`。
 - MUST：审计使用固定 `markdown-it-py==3.0.0` 的 CommonMark parser，只接受真实 `h2` token，且 token 对应源码行必须精确等于 `## Code Review Rules`；不得维护平行的手写 Markdown 状态机。
 - MUST：直接依赖 `markdown-it-py==3.0.0` 与传递依赖 `mdurl==0.1.2` 在本地入口和两条基线 workflow 中显式校验或固定安装，不得依赖运行环境碰巧预装的版本。
 - MUST：中央审计不抓取 GitHub/Codex 页面、不调用私有接口，也不声称验证 Automatic reviews 设置或模型审查质量。
+- MUST：中央审计验证纳管产品仓库关闭 Auto-merge；分支自动删除取决于项目真实分支模型，不由公共审计强制。人工合并前是否完成当前 HEAD Review、解决 thread 与风险分类，由真实 PR 验收，不伪装成静态仓库审计结论。
 - MUST：官方设置通过真实 PR 验收：Automatic reviews 能产生审查；必要时 `@codex review` 能触发人工兜底；Reviewer 能遵循仓库规则。
 - MUST：接入不得新增 review 专用 secret、GitHub App、workflow、runner 或发布权限。
 - 项目扩展点：保存测试 PR、Review 链接和观察期结论的方式。

scripts/audit_github_baseline.py

@@ -531,6 +531,10 @@ def build_source(repo: str) -> RepositorySource:
     source = RepositorySource(repo=repo, workflows={}, tree={})
     if metadata.get("default_branch") != "master":
         source.errors.append("[DEFAULT_BRANCH] 仓库 default_branch 必须是 master")
+    if metadata.get("allow_auto_merge") is not False:
+        source.errors.append(
+            "[REPOSITORY_MERGE_POLICY] 官方 Review 尚非 required check，仓库必须关闭 Auto-merge"
+        )
 
     workflows = gh_api_paginated(repo, "actions/workflows", "workflows")
     for workflow in workflows:

templates/AGENTS.md

@@ -27,7 +27,7 @@
 
 - 只报告可证实且会造成实际影响的问题；尤其关注正确性、性能、回归、安全、隐私、权限、可维护性等风险。
 - 检查数据/API 与跨仓协议兼容、CI/CD 权限边界、失败/回滚路径及测试能否证明这些高风险行为。
-- 把 PR 说明和已有测试视为待验证声明，不重复 lint、格式化或纯风格意见，不要求与当前风险无关的工作；项目重点：PROJECT_REPLACE_REVIEW_RULES
+- 把 PR 说明和已有测试视为待验证声明，不重复 lint、格式化或纯风格意见，不要求与当前风险无关的工作；官方 Review 当前不是 required check，且 GitHub 对有写权限者推送新提交不保证自动关闭 Auto-merge；v1 暂不允许对单个 PR 开启 Auto-merge，只在 Review 当前 HEAD、全部 review thread 已解决后人工合并；项目重点：PROJECT_REPLACE_REVIEW_RULES
 
 ## CI/CD 公共门禁
 
@@ -42,6 +42,7 @@
 - 发布、手动部署、self-hosted、`dev` Environment 和发布 secret 能力只存在于唯一受控 release workflow；按真实拓扑维护 `.github/release-safety.yml`，不要把模板 job/step ID 当成公共事实。
 - 项目可执行契约测试负责证明 ref/内容 ID、容器内 smoke、回滚命令和实际目标 SHA；固定 `100755` wrapper 内部调用项目测试，`PR container validation` job 名称必须唯一、无依赖且无条件执行，workflow/job/targeted step 不得自定义 shell 或工作目录，targeted step 只以精确单行 `run` 执行 manifest 声明路径。中央审计只验证 manifest 与结构化 YAML 高层约束，不解释任意 shell 控制流。
 - `master` 要求 GitHub Actions 产生的 `PR container validation`，启用 strict、管理员保护和对话解决，禁止 force push 与删除。
+- 官方 Review 尚非当前 HEAD 的 required check 时，仓库保持 `allow_auto_merge=false`；只在 Review 当前 HEAD、全部 review thread 已解决且 required checks 成功后人工合并。只有仓库仅使用临时 PR head 分支，或所有长期 head 分支受保护时，才设置 `delete_branch_on_merge=true`。
 
 ## 项目命令
 

tests/fixtures/good/repo.json

@@ -1 +1 @@
-{"full_name": "example/project", "default_branch": "master"}
+{"full_name": "example/project", "default_branch": "master", "allow_auto_merge": false, "delete_branch_on_merge": true}

tests/fixtures/repository-auto-merge-enabled/repo.json

@@ -0,0 +1 @@
+{"full_name": "example/project", "default_branch": "master", "allow_auto_merge": true, "delete_branch_on_merge": true}