发布恢复运行手册

当发布序列在执行途中失败时用于将仓库恢复到可用状态的恢复流程，附带逐阶段诊断。

当一次原地清空式发布序列在执行途中失败时，本运行手册将 ahmed-g-gad/apothem 恢复到可用状态。在发布过程中，公开仓库不会被删除或重建。恢复依赖于发布专属的历史安全标签、维护者的本地克隆以及下游包管理器状态。

1. 阶段分类

阶段	操作	失败模式	恢复路径
1	捕获并推送历史安全标签	标签缺失、未签名，或指向错误的图谱	在移动 `main` 之前，从压缩前的合并点重建该标签
2	验证 CI、审计堡垒、包状态与变更日志	任一关卡失败	停止；在本地修复；不要移动 `main`
3	将 `main` 移动到已签名的单个发布提交	force-with-lease 失败、提交未签名，或提交消息有误	将本地 `main` 重置到预期的已签名提交，并以全新的 lease 重试
4	发布 GitHub Release、Pages、npm 与元数据	某个发布器或验证面失败	保留发布提交；记录失败后仅重新运行失败的发布器

每个恢复操作都是幂等的。在干净状态上运行它是无操作；在部分完成的状态上运行它则会恢复到预期的阶段后状态。

在任何历史重写之前先验证安全标签：

git fetch origin --tags
git show --summary --show-signature <history-safety-tag>
git merge-base --is-ancestor origin/main <history-safety-tag>

预期结果：标签存在，标签已签名时签名验证成功，并且从该标签可以到达压缩前的完整图谱。如果标签在本地缺失但远端存在，则将其拉取下来。如果它在远端缺失，则停止发布，并在触碰 main 之前重建它：

git tag -s <history-safety-tag> <pre-squash-commit>
git push origin <history-safety-tag>

诊断公开的 main 状态：

gh api repos/ahmed-g-gad/apothem/commits/main \
  --jq '.sha, .commit.message, .commit.verification.verified, .commit.verification.reason'

切换之后的预期结果：消息恰好为 release: Apothem <release-version>，且 verification.verified 为 true。

如果 force-with-lease 推送在更改 GitHub 之前就失败了，则保持远端原样，将其拉取下来，在本地重建已签名的发布提交，并仅在 lease 匹配之后重试：

git fetch origin main
git push --force-with-lease=main:<expected-remote-sha> origin main

如果推送已落地但提交未签名或未验证，则修复本地签名配置，从同一棵树重新创建发布提交，并再次以 lease 强制推送。不要删除安全标签。

在 GitHub 发布提交得到验证之后，每个发布器都独立重试：

面	诊断	恢复
GitHub Release	`gh release view <release-tag> --json tagName,isDraft,isPrerelease,assets`	仅删除格式错误的草稿；否则使用 `gh release upload --clobber` 上传缺失的产物
发布标签	`git ls-remote origin refs/tags/<release-tag>` 与 `git tag -v <release-tag>`	如果标签缺失或未签名，则用 `-a -s` 从同一 SHA 重新打标签；切勿为另一个提交复用某个标签名
npm	`npm view @ahmed-g-gad/apothem version` 与 `npx @ahmed-g-gad/apothem@<version> --version`	在确认 `@ahmed-g-gad/apothem` 的 npm Trusted Publishing 之后，针对 `<release-tag>` 重新运行 `publish-npm.yml`
Pages	`gh run list --workflow=publish-static-site.yml --limit=1` 与 `curl -sSI https://apothem.ahmedgad.com/`	重新运行 `publish-static-site.yml`；验证 CNAME 仍解析到 `ahmed-g-gad.github.io`
GitHub 元数据	`gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility`	原地修补描述、主页与主题；不要重建仓库

回滚是最后手段。优先尝试有针对性的发布器恢复。如果必须撤回这个单一发布提交，则从安全标签恢复 main：

git fetch origin --tags
git switch main
git reset --hard <history-safety-tag>
git push --force-with-lease origin main

回滚之后，重新运行 CI，如果 GitHub 报告漂移则重新应用分支保护，并将此次回滚记录为一次阻断发布的事件。仅当发布产物仍然有效时才保留发布标签；否则在重试之前删除格式错误的发布与标签。