devops: AGENTS.md and CONTRIBUTING.md still say PRs are squash-merged

[alchemydc]

Describe the issue or request

AGENTS.md and CONTRIBUTING.md both tell contributors that PRs are squash-merged. That is no longer how this repository merges, and the stale claim actively undercuts the commit-hygiene rule printed on the very next line.

AGENTS.md:121:

• PR titles must follow conventional commits (PRs are squash-merged — the PR title becomes the commit message)
• Do not add Co-Authored-By tags for AI tools

CONTRIBUTING.md:27:

4. Follow conventional commits. PRs are squash-merged to main, so the PR title becomes the commit message.

Current Behavior

Repository settings and Mergify config both say merge commits:

$ gh api repos/ZcashFoundation/zebra --jq '{squash:.allow_squash_merge, merge:.allow_merge_commit, rebase:.allow_rebase_merge}'
{"squash":false,"merge":true,"rebase":false}

.github/mergify.yml sets merge_method: merge in its default queue_rule.

main's history matches: recent merges are two-parent merge commits whose subject is <PR title> (#<number>), with each PR's individual commits preserved alongside them:

$ git log --format='%h parents=%p %s' -5
8e9ff3b2c parents=d098d0181 f3b941e5c chore(chain): update checkpoints (#11148)
d098d0181 parents=9487509d1 53a47b744 docs(security): update disclosure contacts and reporting requirements (#11174)
53a47b744 parents=7e0371da2 9487509d1 Merge branch 'main' into docs/security-report-version-check
f3b941e5c parents=9487509d1 chore(chain): update checkpoints
9487509d1 parents=da29357c7 fd2dc730c fix(network): remove every address book entry for a banned peer IP (#11173)

Why this matters beyond a doc typo

The parenthetical implies that only the PR title reaches main, so individual commit messages don't need care. Two consequences:

1. Individual commits now land on main verbatim. Under merge_method: merge the branch commits are preserved, so anything in a commit message — including Co-Authored-By trailers for AI tools, which AGENTS.md:122 prohibits — persists in permanent history.
2. It was never true even under squash. The repo's squash message setting is COMMIT_MESSAGES, which concatenates the branch's commit messages into the squashed body. So a trailer added to a branch commit would have survived a squash merge too.

The rule is already broadly unenforced, which is consistent with contributors trusting the doc:

$ git log --format='%H' --grep='Co-authored-by:.*\(anthropic\|Copilot\|Claude\)' -i | wc -l
24

Those 24 commits on main include Co-authored-by: Copilot Autofix powered by AI <...> and a range of Co-Authored-By: Claude Opus 4.x <noreply@anthropic.com> trailers.

Found while reviewing #11128, whose commit fe96728 adds the Copilot Autofix trailer — the review asked for an amend, which is only worth asking for because the merge strategy preserves it.

Expected Behavior

Both documents describe the actual merge strategy, and the commit-hygiene rule reads as load-bearing rather than vestigial.

Possible Solution

1. Correct AGENTS.md:121 and CONTRIBUTING.md:27 to say merge commits, noting that the PR title still becomes the merge commit subject (so the conventional-commits requirement is unchanged) and that individual commit messages are preserved on main.
2. State explicitly that the Co-Authored-By prohibition therefore applies to every commit in a PR, not just the title.
3. Decide whether to enforce it rather than document it. Given 24 existing violations, a commit-message check in the PR gate would be more durable than a guideline — worth weighing against added gate surface. Existing history is not rewritable, so this is forward-only.

Additional Information/Context

• Part of the Improve CI epic Improve CI #11196.
• Related to Evaluate and possibly retire Mergify Evaluate and possibly retire Mergify #11197: if the queue implementation changes (see also devops: evaluate replacing Mergify's queue with GitHub native merge queue #11204 on GitHub's native merge queue), the merge-strategy wording will need revisiting again, so it is worth stating the strategy in exactly one place that both documents reference.
• Enable merge commits #10196 ("Enable merge commits") is still open, but merge commits are already enabled and squash disabled at the settings level — that issue may need closing or re-scoping, and it is plausibly when these doc lines went stale.

---

Filed with assistance from Claude Code; the underlying merge-strategy discrepancy surfaced during a cross-review of #11128 with OpenAI Codex.