AI

只做完创建和列表的令牌 PR,写了 Fixes

This post is currently available in Chinese only. The original text follows.Open the Chinese page →

三人、七台电脑。1 到 3 号机跑编码代理,4、5 号机审查,6 号机做 Windows 验证,7 号机负责合入。这套班子共用一块看板。一张票从待办变成完成,常常不是有人亲手点了关闭,而是合并的时候 GitHub 看见了 Fixes #88。

这周的票是给脚本和 CI 加上个人 API 令牌。验收写得很清楚:创建时完整值只出现一次,只存哈希;列表只返回 id、名字和创建时间,不能带出密钥;撤销之后,用这枚令牌再调接口必须失败。1 号机的代理隔夜开工。周一早上,PR 已经开着,测试 2 通过,正文最后一行是 Fixes #88。撤销还在源码里的 TODO 注释里。

我在本机把这件事做成了玩具仓库,又在一个私有沙箱里对着真实的 GitHub 关票逻辑跑了四次合并。部分实现的提交是 b0b8753:有 create_token 和 list_tokens,没有 revoke_token。那两条测试确实 2 通过。我另写了一个探测脚本:创建一枚令牌,试着撤销,再做一次认证。部分实现上,探测的退出码是 2,has_revoke 为 false,令牌在这次“撤销尝试”之后仍然有效。完整实现的提交是 1dce48f,测试 3 通过,探测里撤销之后认证结果是 None。

4 号机如果只看测试和 PR 说明,会觉得这张票做完了。7 号机一合并,票就会从看板上消失。等到有一枚令牌真的泄露,产品里没有地方能把它作废,而看板上已经没有这张票了。

这篇要核对的是:Fixes、Closes、Resolves 这些关闭关键字,到底在什么文字进入默认分支时会关票;人把 PR 正文改成 Refs 之后,提交说明里的 Fixes 还会不会关;只扫正文的闸门会不会漏;验收框被代理自己勾掉算不算数。它和 1 号机和 3 号机同时看见 Issue #88 谈的是谁先开工,和 说了做完,不等于做完了 谈的是模型有没有把话说满,都不是同一件事。今天只谈:票被关上,是不是因为工作做完了。

写了 Fixes 的部分实现一进默认分支,整张票就会被关上

实验室怎么搭

本地玩具仓库的默认分支 main 起点是 61cc798,上面还没有令牌模块。功能分支 feat/api-tokens 加上部分实现,提交 b0b8753 的说明是 feat: add token create and list,正文里有一行 Fixes #88。对比用的完整实现在另一条分支上,提交是 1dce48f,多了 revoke_token 和 test_revoke_rejects_later_calls。合入闸门 merge_if_issue.py 在快进 main 之前扫描 PR 正文和 base..head 范围内的提交说明,按不同模式判定 ALLOW 或 REFUSE。本地看板 issue_board.py 按 GitHub 文档的规则模拟关票:只有进入默认分支的文字才会关票;合并提交会把原提交说明带上 main,squash 则只留下 squash 说明。

关闭关键字的识别按官方文档列出的词:close、closes、closed、fix、fixes、fixed、resolve、resolves、resolved,大小写不敏感,后面可以跟冒号,同一仓库的形式是 KEYWORD #N。Refs #88、Part of #88、Related to #88、See #88 都不算关闭。本地扫描器里,fixing #88 和 hotfix #88 也没有被当成关键字;这两条只在本地验证过,我没有拿到 GitHub 上去试。

真实的关票行为必须问 GitHub 自己。我建了一个私有沙箱仓库,创建了四张内容相同的票,分别对应四种合入条件。每张 PR 的代码都是同一份部分实现:创建和列表,没有撤销。沙箱仓库是私有的,读者进不去,下面给出的票号、PR 号、短哈希和关闭时间都来自这次 API 记录。时间统一写成 Asia/Shanghai。

测试和闸门都在本机 Linux 上跑。我没有把玩具仓库的闸门接到 GitHub Actions,也没有配置分支保护或合并队列。后面给出的本地短哈希在这次固定作者时间的重建里是稳定的;沙箱里的哈希是 GitHub 上的真实提交。

正文里的 Fixes,squash 进 main 后两秒就把票关上了

沙箱的 A 是最常见的路径。Issue #1 的验收三条都未勾。PR #2 的正文写明“只做了创建和列表,撤销不在这次 PR 里”,同时又写了 Fixes #1。7 号机如果只看这段说明,已经能读到自相矛盾,但 GitHub 不会读这句话的意思,它只认关键字。

我用 squash 把 PR #2 合进 main,并让 squash 说明保留了 PR 正文。落在默认分支上的提交是 417b36c,说明里仍然有 Fixes #1。PR 的 mergedAt 是 18:43:37,Issue #1 的关闭事件在 18:43:39,间隔约两秒,事件挂在 417b36c 上,操作者是这次推送用的账号。票的状态从 OPEN 变成 CLOSED。代码里依然没有 revoke_token。

本地这边,对应的无完整性检查路径会放行并快进。main 从 61cc798 走到 b0b8753,测试仍是 2 通过,探测里泄露的令牌照样能通过认证,本地看板把 #88 标成已关闭。测试绿和关票,在这里是同一件错事的两个面:测试没覆盖撤销,关票逻辑也不看撤销在不在。

正文改成 Refs 不够,提交里的 Fixes 仍会关票

更值得写成规则的是 B。有人已经意识到这张 PR 没做完,把正文改成了 Refs #3。看起来谨慎。但代理在提交说明里写的仍是 Fixes #3。PR #4 用合并提交合进 main,合并提交 c69c222 的说明是 GitHub 默认的 “Merge pull request #4 …”,里面没有关闭关键字。

Issue #3 还是被关上了。关闭时间是 18:44:05,比 mergedAt 18:44:04 晚大约一秒。关闭事件挂的不是合并提交 c69c222,而是功能提交 16a565a。那次提交的说明就是 feat: add token create and list 加上 Fixes #3。GitHub 的文档写过:提交说明里的关闭关键字,会在该提交进入默认分支时关票,而且不一定把 PR 列为关联项。这次实测对上了:关票的是进入 main 的那次功能提交,不是合并提交本身。

如果 7 号机的闸门只扫 PR 正文,就会放行这条路径。本地我专门跑了 body_only:正文是 Refs #88、提交里是 Fixes #88 时,判定是 ALLOW,理由是“正文没有关闭关键字(未扫描提交)”。换成扫描 base..head 的 range 模式,判定是 REFUSE,列出的关闭项来自 b0b8753。我在一份克隆上执行了这个拒绝,main 仍停在 61cc798,没有快进。

这才是代理工作流里真正容易漏的缝。人改 PR 正文很便宜,改已经推上去的提交说明要再 commit --amend 或者 rebase,代理不一定会做。审查意见里写“别用 Fixes,这张票还没完”,如果只改了描述,合并提交一旦把旧说明带上 main,票照关。

不要把 squash 当成保险

沙箱的 C 看起来像一个反例。PR #6 的正文是 Refs #5,功能提交 6f9f6e6 里仍然写着 Fixes #5。我用 squash 合进 main,并且把 squash 说明强制写成纯标题:feat: add token create and list (squash title only)。落在默认分支上的提交是 9d7813b,说明里没有关闭关键字。Issue #5 在合并之后仍是 OPEN,事件列表是空的。

这不能当成政策。C 保持开放,只是因为这次 squash 说明被我写成了纯标题。GitHub 仓库可以设置 squash 默认模板,把提交说明或 PR 正文拷进那次落盘提交。我在本地模拟了“标题加上提交详情”的模板:squash 说明里一旦再次出现 Fixes #88,本地看板就会关票。仓库设置改一次,或者某次有人手滑选了“附带提交说明”,所谓保险就消失了。合入方式是变量,7 号机的闸门不能假设大家永远 squash,更不能假设 squash 说明永远是纯标题。

沙箱的 D 对上了文档里关于默认分支的限制。PR #8 指向 develop,正文和提交都写了 Fixes #7,用合并提交合进去,合并提交是 8582b3f,mergedAt 是 18:45:37。Issue #7 仍是 OPEN,没有关闭事件。关键字在非默认分支上会被忽略。这不是安全网:把 develop 快进到 main 的下一次合并,如果那次提交说明还带着 Fixes,票还是会被关上。我没有再做“先合进 develop、再把 develop 合进 main”的第二次合并,所以后半句只是文档含义,不是这次沙箱里测到的结果。

沙箱里四种合并,哪一次真的把票关上了

验收框没有操作者,完整测试和别人贴的标签才能挡住

部分实现已经能让测试 2 通过,所以“测试绿才能合”挡不住关票。我又试了几种看起来更像完整性检查的闸门,全部跑在同一份 b0b8753 上。

按验收框来:Issue 正文里三条都是 - [ ] 时,checkbox 模式拒绝,未勾的项目包括撤销。接着我模拟代理把三个框都改成 - [x],同一份没有 revoke_token 的树,闸门变成 ALLOW,理由是“全部勾选(没有记录操作者)”。Markdown 勾选只是 Issue 正文里的字符,GitHub 并不把“谁勾的”当成一种独立的审查动作。代理改 Issue 正文,和它改自己的 PR 描述一样便宜。把验收框当门禁,等于把钥匙交给写 PR 的那一方。

按必测项来:我要求 test_revoke_rejects_later_calls 必须出现在测试文件里,并且 pytest 要通过。部分实现缺这个测试,required_tests 拒绝。完整实现 1dce48f 上,测试 3 通过,探测里撤销生效,闸门放行。这条有用,但有范围:它依赖有人事先把验收项写成具体的测试名字。换一张票,就要换一份名单。没有维护这份映射时,不要把它当成通用门禁。

按标签来:缺少 issue-complete 就拒绝;标签是 PR 作者自己贴的,也拒绝;标签由 machine-4-reviewer 贴、作者是 machine-1-agent 时,才放行。这才接近“另一台审查机确认这张票做完了”。可是三人七机的环境里,七台电脑经常共用同一个 GitHub 登录。若 4 号机和 1 号机在 API 里是同一个 actor,这条闸门会一直拒绝,或者反过来形同虚设。要用标签,审查机必须有一个与开发机不同的身份;否则就把关票的动作留给会看 diff 的人,不要自动化。

还有一种不靠“证明做完”、只避免误关的做法:rewrite_refs 把正文里的关闭关键字改写成 Refs #88,然后允许合并。本地跑完之后,看板里的 #88 仍是 OPEN。部分实现可以先上 main,撤销还留在待办里。这适合必须先交付创建和列表、撤销要另开一张票的情况。要注意:如果提交说明里还有 Fixes,只改正文不够,必须连提交范围一起改写或重写历史,否则合并提交仍会把旧说明带上默认分支。

7 号机该扫正文和提交范围,而不是只看验收框

机制:关票是完成信号,不是完整性检查

GitHub 关票,是因为一段被它认作关闭关键字的文字,随 PR 正文或提交进入了默认分支。它不打开工作区,不跑 probe_revoke.py,也不理解“撤销不在这次 PR 里”这句人话。看板上的 Done,来自一次文本匹配。

代理会写 Fixes,常常不是因为恶意,而是因为模板、习惯和训练分布把“关联这张票”和“做完这张票”写成了同一句话。一夜之间开出的 PR,正文末尾带上 Fixes #88,在三人七机的节奏里非常常见。审查的人如果只改描述、不改提交说明,就会留下沙箱 B 那种缝。合入方式再决定哪些文字真正落到 main 上:合并提交保留原说明,squash 只保留 squash 说明,仓库模板又可以随时把原说明填回来。

所以问题不在“GitHub 关票关错了”。按它自己的规则,它关对了。错在团队把这个信号当成了完整性检查。测试只覆盖了代理做完的那两步,探测才能证明第三步不存在。如果 7 号机在合并前不扫提交范围,人在界面上看到的 Refs 并没有约束力。

把大票拆成可关闭的子票,是从源头缩小这个问题。创建、列表、撤销各是一张子票,代理在创建那张 PR 上写 Fixes,关的是子票,父票还在。我这次没有在沙箱里再建子票去验证父票会不会被连带关闭,所以不把“父票一定留着”写成测到的结果。它仍然是可用的工作习惯:一张票只对应一个可关闭的完成定义,Fixes 才有资格出现。

什么时候不要装这套闸门

如果团队的票本来就小,一张票就是一个可交付的单元,而且审查之后确实做完了,Fixes 是有用的自动化,不必禁止。闸门应该拦的是“部分实现还在用完成信号”,不是所有关闭关键字。

不要把必测项名单写死成唯一规则,然后在每张票上都猜测试函数名。没有维护映射时,宁可用 range 拒绝关闭关键字,让人来关票,或者改写成 Refs。

也不要把 issue-complete 标签装在共用同一个 GitHub 账号的七台机器上,然后指望它能区分作者和审查者。身份都撞车时,这条规则不是严格,是失效。要么给审查机单独的身份,要么把关票留在人手上。

不要靠“我们都用 squash”来擦掉提交说明里的关键字。沙箱 C 是我故意写成纯标题才保住了 Issue #5。默认模板、一次手选、一次 rebase 合并,都可以让关键字重新落到 main 上。

明天可以抄的

在 1 到 3 号机的 AGENTS.md 里写清楚:未完成全部验收时,不要在 PR 正文或提交说明里写 Fixes、Closes、Resolves。默认写 Refs #N,把关票留给审查或合入闸门。大票先拆子票,子票才用 Fixes。

7 号机在合并前跑 merge_if_issue.py 的 range 模式,同时扫 PR 正文和 base..head 的提交说明。只扫正文不够,沙箱 B 已经证明了这一点。看见关闭关键字,就拒绝自动关票:改写成 Refs 再合,或者要求一张由不同 actor 贴上的 issue-complete,或者对这张票点名的回归测试已经存在并且通过。不要用 Markdown 验收框代替以上任何一项。

合并之后,如果这张票原来包含“撤销”“回滚”“作废”这类验收,用一个探测脚本问产品里能不能真正做到。本地这次的探测很窄:有没有 revoke_token,调用之后认证是不是失败。2 通过的测试回答不了这个问题。

脚本、示例工作流和 AGENTS.md 片段在 issue-complete-kit.tar.gz。可以这样调用闸门:

python3 tools/merge_if_issue.py --repo . --base <default-branch-sha> --head HEAD \
  --pr-body "$(cat pr-body.md)" --mode range
python3 tools/merge_if_issue.py --repo . --base <default-branch-sha> --head HEAD \
  --pr-body "$(cat pr-body.md)" --mode rewrite_refs

示例工作流 YAML 只检查了结构,没有在 GitHub Actions 里跑过。

今天最小的一步:打开一张准备合的代理 PR,搜索正文和 git log main..HEAD 里有没有 Fixes、Closes、Resolves。如果有,先看这张票的验收是不是都在这个 diff 里。不在的话,把关键字改成 Refs,不要让 7 号机带着完成信号去合。

实际跑了什么

运行环境:本机 git 2.47.3、Python 3.13.5、pytest 9.1.1;GitHub CLI 2.103.0。本地种子 61cc798,部分实现 b0b8753(测试 2 通过,has_revoke_symbol=false,探测退出码 2,撤销尝试后令牌仍有效),完整实现 1dce48f(测试 3 通过,探测里认证变为 None)。无完整性检查的快进把 main 带到 b0b8753,本地看板关闭 #88。body_only 在正文为 Refs、提交为 Fixes 时放行;range 拒绝,克隆上 main 未移动,仍为 61cc798。未勾验收框时 checkbox 拒绝,代理勾完后放行。required_tests 在部分实现上拒绝、在完整实现上放行。issue-complete 缺标签或由作者所贴则拒绝,由 machine-4-reviewer 所贴则放行。rewrite_refs 放行且本地看板保持 OPEN。

GitHub 沙箱(私有仓库,2026-11-17)四次合并:PR #2 squash,正文 Fixes #1,落盘提交 417b36c,Issue #1 于 18:43:39(Asia/Shanghai)关闭,事件挂在 417b36c;PR #4 合并提交,正文 Refs #3,功能提交 16a565a 含 Fixes #3,Issue #3 于 18:44:05 关闭,事件挂在 16a565a 而非合并提交 c69c222;PR #6 squash 说明为纯标题 9d7813b,Issue #5 保持 OPEN;PR #8 合进 develop,正文和提交均为 Fixes #7,Issue #7 保持 OPEN。

未运行:GitHub Actions(YAML 只做结构检查)、分支保护或 ruleset、合并队列、第二套 GitHub 账号去点审查标签、Windows 作业或 windows-latest 运行器、把 develop 再合回 main 的第二次合并、以及把 fixing / hotfix / PR 评论区里的关键字送到 GitHub 去验证。本地短哈希在这次固定时间戳的重建中稳定;沙箱哈希是这次 API 调用看到的真实提交。

Three people, seven machines. Machines 1–3 run coding agents, 4 and 5 review, 6 does Windows validation, 7 merges. They share one board. A ticket moves from To Do to Done not because someone clicked Close, but because GitHub saw Fixes #88 at merge time.

This week’s ticket is personal API tokens for scripts and CI. The acceptance criteria are specific: on create, the full value is shown once and only the hash is stored; list returns id, name, and created time, never the secret; after revoke, a call with that token must fail. Machine 1’s agent started overnight. By Monday morning a PR was open, tests were 2 passed, and the last line of the body was Fixes #88. Revoke was still a TODO comment in the source.

I built this as a toy repository on this machine, and I also ran four real merges against GitHub’s close-on-merge behavior in a private sandbox. The partial commit is b0b8753: it has create_token and list_tokens, and it does not have revoke_token. Those two tests really were 2 passed. I also wrote a probe: create a token, try to revoke it, authenticate again. On the partial tree the probe exits 2, has_revoke is false, and the token is still valid after the revoke attempt. The complete commit is 1dce48f, tests 3 passed, and after revoke the probe’s authenticate result is None.

If machine 4 only looks at the tests and the PR description, the ticket looks finished. Once machine 7 merges, the ticket disappears from the board. When a token later leaks, there is no in-product way to revoke it, and the board no longer has a ticket for that work.

This post checks when Fixes, Closes, and Resolves actually close an issue once that text reaches the default branch; whether Fixes in a commit still closes after a person has edited the PR body to Refs; whether a body-only gate misses that case; and whether checkboxes the agent ticks itself count as completion. It is not the same question as who starts Issue #88 when two machines see it, and it is not the same question as said done is not done. Today is only this: was the ticket closed because the work was finished?

A partial PR that says Fixes closes the whole ticket once it reaches main

How the lab was set up

The local toy repository’s default branch main starts at 61cc798, with no token module yet. Branch feat/api-tokens adds the partial implementation. Commit b0b8753 has the subject feat: add token create and list and a body line Fixes #88. A complete implementation lives on a second branch at 1dce48f, with revoke_token and test_revoke_rejects_later_calls. The merge gate merge_if_issue.py scans the PR body and the commit messages on base..head before it will fast-forward main, and it returns ALLOW or REFUSE under several modes. The local board issue_board.py follows the documented GitHub rule: only text that lands on the default branch closes an issue. A merge commit carries the original commit messages onto main; a squash leaves only the squash message.

Closing keywords follow the list in the official docs: close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved, case-insensitive, optional colon, same-repo form KEYWORD #N. Refs #88, Part of #88, Related to #88, and See #88 are not closing forms. In the local scanner, fixing #88 and hotfix #88 were also not treated as keywords. Those two checks are local only; I did not send them to GitHub.

The real close behavior has to come from GitHub itself. I created a private sandbox repository and opened four issues with the same acceptance list, one for each merge condition. Every PR used the same partial implementation: create and list, no revoke. The sandbox is private, so readers cannot open it. The issue numbers, PR numbers, short hashes, and close times below are from this API run. Times are in Asia/Shanghai.

Tests and gates ran on this Linux machine. I did not hook the toy gate up to GitHub Actions, and I did not configure branch protection or a merge queue. Local short hashes are stable in this run because author and committer dates were fixed. Sandbox hashes are the real commits on GitHub.

Fixes in the PR body closed the issue two seconds after a squash onto main

Sandbox case A is the common path. Issue #1 had all three acceptance boxes unchecked. The body of PR #2 said the work was create and list only, and that revoke was not in this PR — and it also said Fixes #1. A reviewer can see the contradiction. GitHub does not read the sentence. It matches the keyword.

I squash-merged PR #2 into main and kept the PR body in the squash message. The commit that landed on the default branch is 417b36c, and it still contains Fixes #1. The PR’s mergedAt is 18:43:37. The close event on issue #1 is 18:43:39, about two seconds later, pointed at 417b36c, with the account that ran the merge as actor. The issue went from OPEN to CLOSED. The tree still has no revoke_token.

Locally, the no-completeness-check path allows the merge and fast-forwards. main moves from 61cc798 to b0b8753, tests are still 2 passed, the probe still authenticates a leaked token, and the local board closes #88. Green tests and a closed ticket are two sides of the same miss: the tests never covered revoke, and the close logic never looked for it.

Editing the body to Refs is not enough if a commit still says Fixes

The case that should become a rule is B. Someone already noticed the PR was incomplete and changed the body to Refs #3. That looks careful. The commit message still said Fixes #3. PR #4 was merged with a merge commit. The merge commit c69c222 has GitHub’s default message, “Merge pull request #4 …”, and that message has no closing keyword.

Issue #3 closed anyway. The close time is 18:44:05, about one second after mergedAt 18:44:04. The close event does not point at merge commit c69c222. It points at feature commit 16a565a, whose message is feat: add token create and list plus Fixes #3. The docs say a closing keyword in a commit message closes the issue when that commit reaches the default branch, and that the pull request may not even be listed as linked. The measurement matches: the close is tied to the feature commit that became reachable from main, not to the merge commit itself.

A gate that only scans the PR body will allow this path. I ran body_only locally: body Refs #88, commit Fixes #88, decision ALLOW, reason “PR body has no closing keywords (commits not scanned).” The range mode, which scans base..head, refused and named b0b8753. I applied that refusal on a clone; main stayed at 61cc798 and did not fast-forward.

That is the seam agent workflows actually fall into. Editing a PR body is cheap. Changing a commit that is already pushed takes amend or rebase, and the agent may not do it. If a review comment says “don’t use Fixes, this ticket is not done,” and only the description is edited, a merge commit will still carry the old message onto main, and the issue will still close.

Do not treat squash as insurance

Sandbox case C looks like a counterexample. The body of PR #6 said Refs #5. Feature commit 6f9f6e6 still said Fixes #5. I squash-merged into main and forced the squash message to a title only: feat: add token create and list (squash title only). The landed commit is 9d7813b, with no closing keyword in the message. Issue #5 stayed OPEN after the merge, and its events list was empty.

That is not a policy. C stayed open only because I forced the squash message to a title. A repository can set a default squash template that copies commit messages or the PR body into the landed commit. I simulated a “title plus commit details” template locally: once Fixes #88 reappeared in the squash message, the local board closed the issue. One settings change, or one person choosing “include commit details,” and the supposed insurance is gone. The merge method is a variable. Machine 7’s gate cannot assume the team will always squash, and it cannot assume the squash message will always be a title.

Sandbox case D matched the documented default-branch restriction. PR #8 targeted develop, the body and the commit both said Fixes #7, and a merge commit 8582b3f landed at 18:45:37. Issue #7 stayed OPEN, with no close event. Keywords are ignored when the PR does not target the default branch. That is not a safety net. The next merge that fast-forwards develop into main can still close the issue if that landed text still contains Fixes. I did not run that second merge, so the last sentence is the documented implication, not a result measured in this sandbox.

Which of the four sandbox merges actually closed the issue

Checkboxes have no actor; a named test or a label from someone else can hold the line

The partial implementation already has 2 passing tests, so “merge only when tests are green” will not stop the close. I ran several gates that look more like completeness checks, all against the same b0b8753 tree.

Checkboxes: with three - [ ] items in the issue body, checkbox mode refuses, and the unchecked list includes revoke. I then had the agent tick all three boxes to - [x]. On the same tree, still without revoke_token, the gate became ALLOW, because “all issue checkboxes are checked (no actor recorded).” A markdown checkbox is just characters in the issue body. GitHub does not record “who ticked this” as a review action. An agent editing the issue body is as cheap as editing its own PR description. Using checkboxes as a gate hands the key to the author of the PR.

Required tests: I required test_revoke_rejects_later_calls to exist in the test file and to pass under pytest. The partial implementation is missing that test, so required_tests refuses. On the complete commit 1dce48f, tests were 3 passed, the probe revoked successfully, and the gate allowed. This is useful, with a limited scope: someone has to map acceptance items to concrete test names. A different ticket needs a different list. Without that mapping, do not treat this as a general-purpose gate.

Labels: missing issue-complete is a refusal; a label applied by the PR author is a refusal; a label applied by machine-4-reviewer while the author is machine-1-agent is an allow. That is close to “the review machine confirmed the ticket is complete.” In a three-person, seven-machine setup, though, all seven computers often share one GitHub login. If machines 4 and 1 are the same actor in the API, this gate will either always refuse or, if you weaken it, mean nothing. To use a label, the review machine needs an identity distinct from the development machines. Otherwise leave closing the issue to a person who read the diff.

There is also a path that does not try to prove completeness, and only avoids a mistaken close: rewrite_refs rewrites closing keywords in the body to Refs #88 and then allows the merge. After that local run, issue #88 stayed OPEN on the board. The partial implementation can land on main, and revoke stays in To Do. That fits a delivery that must ship create and list now, with revoke as a new ticket. If a commit message still says Fixes, rewriting the body is not enough. The commit range has to be rewritten too, or a merge commit will carry the old message onto the default branch.

Machine 7 should scan the body and the commit range, not the checkboxes

The mechanism: a close is a completion signal, not a completeness check

GitHub closes the issue because a stretch of text it treats as a closing keyword reached the default branch, in a PR body or in a commit. It does not open the worktree, it does not run probe_revoke.py, and it does not understand the sentence “revoke is not in this PR.” Done on the board is a text match.

Agents write Fixes not usually out of malice. Templates, habit, and training data collapse “link this ticket” and “finish this ticket” into the same sentence. Overnight PRs that end with Fixes #88 are common on a three-person, seven-machine cadence. If the reviewer only edits the description and not the commit message, you get the seam from sandbox case B. The merge method then decides which text actually lands on main: a merge commit keeps the original message, a squash keeps only the squash message, and a repository template can copy the original message back in.

So the bug is not that GitHub closed the wrong issue. Under its own rules, it closed the right one. The mistake is treating that signal as a completeness check. The tests only covered the two steps the agent finished. The probe is what shows that the third step is missing. If machine 7 does not scan the commit range before merge, the Refs a person typed into the UI has no force.

Splitting a large ticket into closable sub-issues shrinks the problem at the source. Create, list, and revoke each get a child issue. If the agent writes Fixes on the create PR, it closes the child, and the parent can stay open. I did not create sub-issues in the sandbox to measure whether a parent would be closed along with a child, so I am not stating “the parent stays open” as a measured result. It is still a working habit: one ticket, one closable definition of done, and only then does Fixes belong.

When you should not install this

If the team already writes small tickets, each one is a single deliverable, and the review really did finish the work, Fixes is useful automation. Do not ban it. The gate should stop a partial implementation from using a completion signal, not every closing keyword.

Do not hard-code a required-test name as the only rule and then guess function names on every ticket. Without a maintained mapping, prefer range refusing closing keywords, let a person close the issue, or rewrite to Refs.

Do not install an issue-complete label on seven machines that share one GitHub login and expect it to tell the author from the reviewer. When the identities collide, the rule does not get stricter. It fails. Give the review machine a distinct identity, or leave closing to a human.

Do not rely on “we always squash” to strip closing keywords from commit messages. Sandbox C kept issue #5 open because I forced a title-only squash message. A default template, a manual choice, or a rebase merge can put the keyword back onto main.

What to copy tomorrow

In AGENTS.md for machines 1–3, say this plainly: if the PR does not finish every acceptance item, do not put Fixes, Closes, or Resolves in the PR body or in a commit message. Default to Refs #N, and leave the close to review or to the merge gate. Split a large ticket into sub-issues, and use Fixes only on a child.

Before machine 7 merges, run merge_if_issue.py in range mode, on both the PR body and the commit messages on base..head. Scanning the body alone is not enough; sandbox case B already showed that. If a closing keyword is present, do not let the issue auto-close: rewrite to Refs and then merge, or require an issue-complete label from a different actor, or require the regression named for this ticket to exist and pass. Do not use markdown checkboxes as a stand-in for any of those.

After merge, if the original ticket included an acceptance item like revoke, roll back, or invalidate, run a probe that asks whether the product can actually do it. The probe in this lab is narrow: is there a revoke_token, and does authenticate fail after it is called? The 2 passing tests do not answer that.

The scripts, a sample workflow, and the AGENTS.md snippet are in issue-complete-kit.tar.gz. Call the gate like this:

python3 tools/merge_if_issue.py --repo . --base <default-branch-sha> --head HEAD \
  --pr-body "$(cat pr-body.md)" --mode range
python3 tools/merge_if_issue.py --repo . --base <default-branch-sha> --head HEAD \
  --pr-body "$(cat pr-body.md)" --mode rewrite_refs

The sample workflow YAML was checked for structure. It was not run on GitHub Actions.

The smallest step today: on an agent PR that is about to merge, search the body and git log main..HEAD for Fixes, Closes, and Resolves. If you find one, check whether every acceptance item is in that diff. If it is not, change the keyword to Refs before machine 7 merges with a completion signal.

What was actually run

Runtime: git 2.47.3, Python 3.13.5, and pytest 9.1.1 on this machine; GitHub CLI 2.103.0. Local seed 61cc798. Partial b0b8753 (tests 2 passed, has_revoke_symbol=false, probe exit 2, token still valid after the revoke attempt). Complete 1dce48f (tests 3 passed, probe authenticate becomes None). The no-completeness-check fast-forward moved main to b0b8753 and the local board closed #88. body_only allowed a Refs body with a Fixes commit; range refused, and on the clone main stayed at 61cc798. checkbox refused when boxes were empty and allowed after the agent ticked them. required_tests refused on the partial and allowed on the complete tree. issue-complete refused when missing or applied by the author, and allowed when applied by machine-4-reviewer. rewrite_refs allowed and the local board stayed OPEN.

GitHub sandbox (private repository, 2026-11-17), four merges: PR #2 squash, body Fixes #1, landed commit 417b36c, issue #1 closed at 18:43:39 Asia/Shanghai, event on 417b36c; PR #4 merge commit, body Refs #3, feature commit 16a565a contained Fixes #3, issue #3 closed at 18:44:05, event on 16a565a not on merge commit c69c222; PR #6 squash message was a title only at 9d7813b, issue #5 stayed OPEN; PR #8 merged into develop with Fixes #7 in body and commit, issue #7 stayed OPEN.

Not run: GitHub Actions (the YAML was checked for structure); branch protection or a ruleset; a merge queue; a second GitHub account to apply a review label; any Windows job or windows-latest runner; a second merge of develop back into main; and sending fixing, hotfix, or a keyword in a PR comment to GitHub for verification. Local short hashes are stable in this fixed-timestamp rebuild. Sandbox hashes are the real commits from this API run.