仓库治理的机械闸:顺序靠脚本和 hook 拦,不靠记性
模块:仓库治理 · 双远端 / 文档门面(tmp/repo-governance)|状态:已落地(2026-10-20 A1–A8)|证据:
tmp/repo-governance/{planning,todos}.md、scripts/sync-remotes.sh、.githooks/pre-push、scripts/check-master-plan.sh、AGENTS.md
1. 场景与病灶
项目要同时进两个私有仓:AtomGit 是主仓(华为云部署从它拉最新代码),GitHub 是镜像。本地原来一个远端都没有,84 个提交只在本机。
故事一(推反了,而且没人知道)。 某天先推 GitHub、再推 AtomGit,第二步时 AtomGit 令牌过期或网络失败。GitHub 已经领先,AtomGit 停在旧版本。华为云照常拉 AtomGit、照常构建成功——产物是旧的,日志里没有任何红灯。发现时很难反推是哪一天、哪一步推失败:两个远端的 main 都「存在且看起来正常」,只有比对 SHA 才看得出谁领先。
故事二(按总纲找施工面,找到一片空地)。 新人或新 agent 进仓库,按 doc/16 读:子代理「⬜ 当前重心」、记忆「⬜」、多用户「⬜」,落点写着 internal/taskboard、internal/webui。这两个包在 v6 已经不存在。读者去一个不存在的目录找代码,浪费一整轮才回来问。
故事三(根 README 的第一步就失败)。 README 写 go run ./cmd/yktako -web ...,v6 没有 -web;写「Web UI 单用户、无鉴权」,实际已有登录和多租户。新人照做,第一条命令就报 unknown flag。
三个故事是两类问题:推送顺序(过程不变量)和门面/索引与代码脱节(信息真源)。两类都试过靠「文档里写一句规矩」来管——结果是规矩在,违反的人也可能没看见,或者看见时已经晚了。这一轮的共同结论:能机械判定的,做成脚本或 hook;不能机械判定的(文档写得对不对),至少把「索引与总纲同批改」做成可执行检查。
2. 候选与代价
| 候选 | 做法 | 好处 | 代价 |
|---|---|---|---|
| A 只在 AGENTS.md 写「先推 AtomGit」 | 靠人记 | 零成本 | 记不住就违反;GitHub 领先时无任何提示 |
| B 加 CI 检查两边 SHA | CI 定时跑 | 事后能发现 | 仓库没有 CI;发现自己已经落后,不能阻止错误发生 |
| C 脚本固定顺序 + pre-push 机械闸(选定) | sync-remotes.sh 先 origin 后 github;.githooks/pre-push 在推 github 时比对 origin 同分支 SHA |
错误在推送那一刻被拦住;不依赖 CI 与记性 | 每个 clone 要装一次 hook;AtomGit 不可达时 GitHub 也推不了(这是期望行为) |
D git push --mirror 一次推完 |
省事 | 一条命令 | 本地还有远端不需要的引用(refs/cline/checkpoints/* 里 47.7MB 的二进制),--mirror 会一起推上去;且没有顺序保证 |
| E 先搬文档再整理 | 先搬家再建索引 | 目录看起来整齐 | 58 个 md 引用 doc/、18 个引用 doc/19-v6,先搬制造大量断链,还掩盖「哪篇过期」这个真问题 |
选 C,并配 E 的反面做法:先建索引、后搬家。
门面这条线的机械闸不是 hook,而是 scripts/check-master-plan.sh:它取 doc/README.md §1「现行真源」表的编号列,逐个 grep doc/16 是否引用;漏引即退出码非零。它不能判断内容写得对不对,但能拦住这两篇最关键的页单边更新——这正是「总纲落后两轮」事故的形状。
3. 闸的判据与边界
3.1 pre-push 的判据
.githooks/pre-push 只在目标远端是 github 时生效。对每个要推的分支:
- 删除分支直接放行(删除不会让 GitHub 领先);
git ls-remote origin refs/heads/<branch>取 AtomGit 上的 SHA;- AtomGit 没有这个分支 → 拒绝(「先推 AtomGit,再推 GitHub」);
- AtomGit 的 SHA ≠ 本地要推的 SHA → 拒绝,并打印两边 SHA 与下一步命令。
判据是同一个 SHA,不是时间戳或版本号——远端没有可靠的「谁更新」信息,SHA 相等是唯一明确的不变量:github/main 可以落后,不能领先;相等就是同步。
安装:每个 clone 执行一次 git config core.hooksPath .githooks。这一点写进 AGENTS.md——hook 不是仓库自带的运行时行为,不装就等于没有闸。
3.2 为什么 AtomGit 不可达时也拒绝推 GitHub
看起来「本地明明有最新代码,GitHub 先推一下做备份」很合理。但那样做的结果正是故事一:GitHub 领先、AtomGit 不知道落后多久。闸的选择是让操作失败得大声,而不是悄悄制造一个更难诊断的分叉状态。
3.3 首次覆盖远端的两个钉子
两仓初始各有一个自动生成的 Initial commit(仅 LICENSE),与本地历史无共同祖先。用户裁定直接覆盖、不保留 LICENSE。覆盖用 --force-with-lease 锁住旧 SHA(AtomGit 5549f74…、GitHub a3227a2… 一类的值),而不是裸 --force——如果远端在这期间有了别人的提交,lease 会失败,避免误伤。
同一原则还落了三条:
- 禁止
--mirror:只推main:main与 tags; - 远端 URL 不写令牌或密码:AtomGit 用 SSH(主机指纹 TOFU 入
known_hosts),GitHub 用 HTTPS + 凭据助手(本机 SSH 22 端口超时); - 不自动改 git config:hook 安装是显式一步。
3.4 门面的顺序:先索引,后搬家
A2–A6 只做「指路」不改文件:
doc/README.md成为索引:现行真源 / 历史存档 / 非方案内容三张表 + 阅读顺序 + 新增文档规则;- 根
README.md与 v6 现状一致(去掉-web、单用户等过期说法); AGENTS.md加仓库地图、文档状态规则、双远端规则;doc/16重基线(状态与代码落点逐条复核);.gitignore只描述当前仓库(.arts/、.merkle-snapshot.json等本地噪声不再进git status)。
为什么先索引:搬家会让 58 处引用同时失效,而「哪篇过期」的问题会被断链噪声淹没。先把真源钉死,第二拍再移动文件——那时每篇的去留已有索引作依据。
4. 同族小裁定
| 小问题 | 裁定 | 代价 / 备注 |
|---|---|---|
| GitHub 允许领先吗 | 不允许,相等或落后 | 华为云只认 AtomGit;领先意味着部署的是旧代码 |
| 推 GitHub 前是否自动推 AtomGit | 不自动,直接拒绝并提示命令 | 自动推会把「忘了推」变成隐式副作用;用户可能只想先本地提交 |
| 删除分支要不要拦 | 放行 | 删除不能让 GitHub 领先 |
| 首次覆盖远端 | --force-with-lease 锁旧 SHA |
裸 --force 会覆盖期间别人的提交 |
git push --mirror |
明令禁止 | 会带上 refs/cline/checkpoints/* 的 47.7MB 二进制 |
| 远端协议 | AtomGit SSH / GitHub HTTPS | 本机 GitHub SSH 22 超时;URL 里永不写令牌 |
| hook 安装 | 每个 clone 手动 core.hooksPath |
不装等于没闸;写进 AGENTS.md |
| 文档搬不搬 | 本轮不搬,只建索引 | 搬家是第二拍;先索引避免断链掩盖过期问题 |
| 总纲与索引一致性 | check-master-plan.sh 机械检查 |
只查编号覆盖,不查内容;内容靠评审 |
| commit 粒度 | 用户定,不自动 commit | 双远端首次推送前先备份,后续提交有退路 |
5. 证据
方案 / 台账:tmp/repo-governance/planning.md(背景、三个故事、目标/非目标、A1–A8 依赖链、风险与回退)、tmp/repo-governance/todos.md(每拍验收第一行打真实远端:git ls-remote / gh repo view)。台账验收后清理,不入库。
代码符号:
| 位置 | 是什么 |
|---|---|
scripts/sync-remotes.sh |
先 git push origin <branch>,成功后才 git push github <branch>(set -euo pipefail) |
.githooks/pre-push |
目标为 github 时,比对 git ls-remote origin refs/heads/<branch> 与本地 SHA;不等即拒 |
scripts/check-master-plan.sh |
取 doc/README.md §1 编号列,检查 doc/16 是否全部引用 |
AGENTS.md「双远端同步」 |
铁律、脚本入口、core.hooksPath、禁 --mirror、URL 不写令牌 |
AGENTS.md「文档状态与真源」 |
doc/ 真源划分;改动产品能力时 README 与 doc/16 同批更新 |
复核命令:
# 远端与顺序(打真实远端)
git remote -v # origin=AtomGit(SSH),github=GitHub(HTTPS)
git ls-remote origin main | cut -f1
git ls-remote github main | cut -f1 # 期望:相等或 github 落后,绝不领先
# 闸本身:本地 hook 是否装上
git config core.hooksPath # 期望:.githooks
# 门面机械闸
bash scripts/check-master-plan.sh # 期望:OK:doc/16 总纲已覆盖 doc/README.md §1 …
# 本地噪声
git status --short # 期望:只出现预期的改动活体验收:2026-10-20 A1 完成——origin / github 均指向本地 HEAD,两边默认分支 main,GitHub 确认 PRIVATE,远端初始提交被 --force-with-lease 覆盖;A2 的 doc/README.md 覆盖 52 篇 doc/ + 18 篇 docs/,四张表 + 阅读顺序 + 新增规则,覆盖检查与链接自检通过。后续每轮收尾跑 check-master-plan.sh。