Three rules in GOVERNANCE.md state their common case correctly and leave the case that actually recurs unstated. Each has produced repeated failures, and in each the failure is read as an agent ignoring the rule when the rule does not reach the situation. They are filed together because they share that shape, they all edit the same carried file, and they all land in one fleet re-vendor.
1. When an issue is closed by hand
$ git show origin/develop:GOVERNANCE.md | sed -n '59p' | cut -c1-316
- **Issue-closing keywords (`Closes #N`, `Fixes #N`) go in the `develop -> main` promotion PR, not the feature -> `develop` PR.** GitHub auto-closes an issue only when the closing keyword merges into the **default branch** (`main`). A feature -> `develop` PR merges into `develop`, so the keyword never fires there.
The rule is stated, and it is carried by every repository, so downstream agents re-deriving it and reporting it as a discovery are missing it rather than lacking it. That part is a discoverability problem, not a wording one.
What the rule genuinely does not cover is the case that produces the confusion: work complete on develop with no promotion imminent. The issue stays open with nothing on it recording that it is done, the next agent to read it treats it as outstanding, and the rule's only licensed hand-close is the narrower "the promotion already merged without the keyword".
Widen it to say an issue is closed when the work is verifiably complete, citing the squash SHA that completed it, and that the promotion keyword is the automation for the common case rather than the only permitted route.
#552 is the live instance, fixed by the merge of #572 and open at the time of writing.
2. The clickable link comes before the prompt, not merely with it
GOVERNANCE.md "Communicating with the User" gets the hard part right. An interactive prompt renders neither a Markdown link nor a bare URL, so the reference inside it is a bare number and the link goes in the message that accompanies it. That reasoning is correct and was not obvious.
The word it uses is accompanying. A message emitted after the prompt is not read before the question is answered, which is the entire outcome the rule exists to produce, so the ordering is load-bearing and unstated. This keeps recurring in practice, which is the evidence that the wording is underspecified rather than that the rule is being ignored.
3. An operational repository still opens a pull request for a large change
GOVERNANCE.md "Operational Repositories" grants the direct commit to develop and says nothing about when to decline the grant.
$ git show origin/develop:repo-config/operational/develop.json | jq -r '.rules[].type'
deletion
non_fast_forward
required_signatures
The release model's develop payload carries a pull_request rule and this one does not, by design, so nothing mechanical stands between an agent and a large unreviewed change landing on the live surface. The reason the grant exists is the one-line config edit that a review round costs more than it protects, and that reason stops applying well before a change gets large.
Settle what counts as large, and prefer a stated shape over a line count, since the property that matters is whether the change can be read at a glance and reverted cleanly rather than how many lines it moved. This stays guidance by construction: adding a pull_request rule to the operational ruleset would withdraw the grant the model exists to give.
Why one issue
All three edit carried GOVERNANCE.md sections, so each one separately is a fleet re-vendor and together they are one. The shared diagnosis is worth keeping in view while writing them, since a rule that covers the common case and goes quiet on the recurring one reads as complete to its author and as absent to its reader.
Filed from the onboarding-feedback pass in #576, where each is recorded as a TODO.md entry.
Three rules in
GOVERNANCE.mdstate their common case correctly and leave the case that actually recurs unstated. Each has produced repeated failures, and in each the failure is read as an agent ignoring the rule when the rule does not reach the situation. They are filed together because they share that shape, they all edit the same carried file, and they all land in one fleet re-vendor.1. When an issue is closed by hand
The rule is stated, and it is carried by every repository, so downstream agents re-deriving it and reporting it as a discovery are missing it rather than lacking it. That part is a discoverability problem, not a wording one.
What the rule genuinely does not cover is the case that produces the confusion: work complete on
developwith no promotion imminent. The issue stays open with nothing on it recording that it is done, the next agent to read it treats it as outstanding, and the rule's only licensed hand-close is the narrower "the promotion already merged without the keyword".Widen it to say an issue is closed when the work is verifiably complete, citing the squash SHA that completed it, and that the promotion keyword is the automation for the common case rather than the only permitted route.
#552 is the live instance, fixed by the merge of #572 and open at the time of writing.
2. The clickable link comes before the prompt, not merely with it
GOVERNANCE.md"Communicating with the User" gets the hard part right. An interactive prompt renders neither a Markdown link nor a bare URL, so the reference inside it is a bare number and the link goes in the message that accompanies it. That reasoning is correct and was not obvious.The word it uses is accompanying. A message emitted after the prompt is not read before the question is answered, which is the entire outcome the rule exists to produce, so the ordering is load-bearing and unstated. This keeps recurring in practice, which is the evidence that the wording is underspecified rather than that the rule is being ignored.
3. An operational repository still opens a pull request for a large change
GOVERNANCE.md"Operational Repositories" grants the direct commit todevelopand says nothing about when to decline the grant.The
releasemodel'sdeveloppayload carries apull_requestrule and this one does not, by design, so nothing mechanical stands between an agent and a large unreviewed change landing on the live surface. The reason the grant exists is the one-line config edit that a review round costs more than it protects, and that reason stops applying well before a change gets large.Settle what counts as large, and prefer a stated shape over a line count, since the property that matters is whether the change can be read at a glance and reverted cleanly rather than how many lines it moved. This stays guidance by construction: adding a
pull_requestrule to the operational ruleset would withdraw the grant the model exists to give.Why one issue
All three edit carried
GOVERNANCE.mdsections, so each one separately is a fleet re-vendor and together they are one. The shared diagnosis is worth keeping in view while writing them, since a rule that covers the common case and goes quiet on the recurring one reads as complete to its author and as absent to its reader.Filed from the onboarding-feedback pass in #576, where each is recorded as a
TODO.mdentry.