todo: propose a standard for commit messages merged into main - #1557

Reviewed at 5db378e960820ec639f89e5add36b97649d885f5, merge-base cb1fcdc457ecb5ba3a20d994e4ba4e0c31d9577e — which is also current origin/main, so the branch is not behind.

Docs-only, confirmed from the merge-base diff rather than the title: three files, all todo/*.md, +179/-0, no code touched. Per AGENTS.md §8.3 no changelog entry is owed, and the description's Changelog: none matches. The build and test gates would be identical to main by construction, so I did not run them.

Since a proposal document's value is its factual accuracy, I re-derived every claim it makes about this repo's history against origin/main. Most reproduce. Two do not.

1. "every commit on main today already has this shape" does not reproduce

todo/commit-message-standard.md line 35, closing the squash-merge bullet:

A squash merge never lands branch commits: it always creates one new commit, parented on the main tip, titled <PR title> (#NNN) — every commit on main today already has this shape.

The mechanism claim before the dash is right. The evidence clause after it is not, under either ruler:

$ git rev-list --count origin/main                                        1881
$ git log --format='%s' origin/main | grep -vcE '\(#[0-9]+\)$'             560
$ git rev-list --count --first-parent origin/main                         1803
$ git log --first-parent --format='%s' origin/main | grep -vcE '\(#[0-9]+\)$'
                                                                          486
$ git rev-list --count --merges origin/main                                15

So 486 of 1803 first-parent commits (560 of 1881 overall) lack the (#NNN) suffix, and main carries 15 merge commits, so it is not linear today either. The newest counterexamples are recent, not ancient:

7b979e74 2026-08-03 0.41.0
830a0c5e 2026-08-02 Fix spelling in comment about optimization

7b979e74 is 11 days old and is a release commit that landed with no (#NNN) — i.e. by direct push, not a squash-merged PR. That is a mild tension with the same document's release-title rule, which is otherwise well supported: 0.45.0 (#1555), 0.44.0 (#1513), 0.43.1 (#1448), 0.43.0 (#1443), 0.42.0 (#1441) all do go through PRs with a bare-version title.

What is true is the narrower statement:

$ git log --first-parent -100 --format='%s' origin/main | grep -vcE '\(#[0-9]+\)$'
0

The last 100 first-parent commits are uniform. So "every commit from the last hundred merges already has this shape" holds; "every commit on main today" does not. Worth narrowing, because the claim is also in slight tension with the Problem section's own premise — the argument for acting now is precisely that pre-standardization history is not uniformly parseable.

2. The "body ends with the Changelog: section" rule is violated by this PR's own description

commit-message-standard.md requires the Changelog: section to be "the last section of the body", and commit-message-enforcement.md specifies the linter as failing "unless the title matches the format and the body ends with a Changelog: section".

The repo's established PR-description shape puts an automated trailer after the prose. Of the last 25 merged PRs, 14 have a Generated with [Claude Code] / Claude-Session: / Co-Authored-By: trailer at the end of the body — including #1556, #1555, #1554, #1553, #1547, #1546, #1545. And this PR's own description ends:

Changelog: none

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01M296KXwQHHuUGhryRReKpJ

So the linter as specified would fail #1557 itself, and roughly half of recent PRs. The fix is small — require the body to contain a Changelog: section and allow a trailer block after it (or define the section as the last section before any trailer, the way git interpret-trailers treats a trailer block) — but "ends with" is the wording the enforcement issue hands to whoever writes the workflow, so it is worth fixing in the proposal rather than in the linter.

Observation, not a defect: the ≤ 72-character title rule

The rule is proposed for the future, so it is not a factual error, but the adoption cost is larger than it may look:

$ git log --first-parent --format='%s' origin/main | awk 'length($0)>72' | wc -l    219
$ git log --first-parent -200 --format='%s' origin/main | awk 'length($0)>72' | wc -l  38

219 of 1803 first-parent titles exceed 72 characters including the (#NNN), and 38 of the last 200 — about 19% of current practice, e.g. Migration close-out: drop the .js ignore, browser-native browser-testing plan, @import sweep (#1545) at 100 characters and Exact emitted declarations: keep every @module header, remove the last elided any (#1526) at 89. Fine as a deliberate tightening; just noting that a required status check would start rejecting titles at that rate on day one.

What checked out

• Tags. "Releases are not tagged (git tag is empty)" — confirmed, 0 local tags and git ls-remote --tags origin returns 0.
• The body premise. Recent squash bodies really are GitHub's default concatenation: cb1fcdc4, 5efbe375, 8804e783, 4fbf0b71 all begin * <branch commit title>.
• The quoted noise strings are real, not illustrative inventions: Address review matches 82 lines and Drop stray blank line 1 line across git log --format=%B origin/main.
• Every referenced path exists and every link resolves: todo/changelog-from-git-history.md, todo/changelog-website.md, todo/commit-message-enforcement.md, changelog/README.md, changelog/unreleased/, fjs/ci/, and AGENTS.md, which does have a §8 with §8.3 and §8.4. No path:line citations to range-check.
• The cross-reference is precise. changelog-from-git-history.md's "design 1" is in fact 1. **Commit-message extraction.** (line 27), so "its Changelog: section is design 1's input" is right.
• "no PR link" in entries matches changelog/README.md as it stands after #1552/#1555: "New entries … contain no links: the file name is the pull-request number".
• Conventions. **Priority:** / **Status:** headers match the sibling todo/changelog-*.md files; P2/P3 versus the investigation's P4 is consistent. todo/README.md is a placement guide, not an index, so no listing was owed.
• Link check. bin/linkcheck.mjs gives 129 broken links in both trees and the sets are byte-identical (diff empty) against origin/main at cb1fcdc4. The three new files strand nothing and add nothing.

Not verified

The claim that commit-metadata rulesets "require an Enterprise plan" is a GitHub plan-tier detail I cannot check from the tree; I did not confirm or contradict it. The pull_request edited trigger and Require linear history branch protection both exist as described.

Both findings are wording-level and neither blocks the direction, which I think is sound — fixing the format before the history accumulates is the right ordering. Commenting rather than approving because item 2 would be inherited by the linter as a spec bug, and item 1 is an existential claim about the repo that a reader would reasonably take as verified.

Re-reviewed at fb689437f426cd6aa11d3e671640bcc4792ec06d (previously commented at 5db378e9), against origin/main = cb1fcdc457ecb5ba3a20d994e4ba4e0c31d9577e. Both findings from the last round are addressed. I recomputed every number from git log rather than reading the new wording.

Finding 1 — "every commit on main today already has this shape" — closed

The claim is now scoped, and each of its parts reproduces exactly on origin/main:

For completeness: across the last 200 first-parent commits there are exactly 2 counterexamples — that 0.41.0 push and Fix spelling in comment about optimization (830a0c5e, 2026-08-02). So "the last hundred" is the tightest true bound, and it is the one stated. Whole-history figures are unchanged since my last round (main has not advanced past #1554), so nothing drifted.

Finding 2 — the rule rejecting its own proposal PR — closed

The spec now reads "the last section of the body before an optional trailer block" in commit-message-standard.md, with the matching phrasing in commit-message-enforcement.md. Checked against this PR's actual description: it ends Changelog: none, then a blank line, then 🤖 Generated with [Claude Code](…) and a session URL — which is precisely the trailer block the reworded rule exempts. The proposal now passes its own linter.

One correction to my own last round, and to the PR's figure. I previously said "14 of the last 25 merged PRs end with such a trailer". That undercounted — it was matching only the Co-Authored-By: / 🤖 Generated with shape and missing the bare https://claude.ai/code/session_… and _Generated by [Claude Code](…)_ forms. Recounting the last 25 merged PRs (#1532–#1556) by their final non-empty body line: 25 of 25 end with a trailer, all of them one of those forms. So the PR's "about half of recent PR bodies end with one" is itself an understatement — it is currently universal. That does not change the design (the exemption covers 100% as well as it covers 50%), but if the number is going to appear in a todo that a future linter is written against, "essentially every recent PR body" would be the accurate phrasing.

Title cap — now stated, and exact

"38 of the last 200 titles exceed it today" reproduces exactly: awk 'length($0)>72' over the last 200 first-parent subjects → 38. Over all 1803 first-parent commits it is 219. Calling the ≤72 cap "a deliberate tightening, not current practice" is the right framing, and my earlier observation is satisfied.

Everything else

Docs-only — three files under todo/, no code touched, so per §8.3 no CHANGELOG entry is needed and correctly none is added. linkcheck broken-link sets are byte-identical to origin/main, so the two new files and the new references from todo/changelog-from-git-history.md strand nothing. No Rust, no generator, no public surface.

Still explicitly unverified, as last round: the "commit-metadata rulesets require Enterprise" plan-tier claim in the enforcement doc. That is a GitHub billing-tier fact I cannot check from here, and the doc's fallback plan does not depend on it.

One cosmetic nit: todo/commit-message-enforcement.md:29 came out 94 characters wide —

when the title or description is fixed — no push needed to re-green. Branch protection marks

— which is the only line over 80 in either changed file; the reflow just missed it.

Approving.