Claims and changelog lines in one file per pull request, so parallel pull requests don't conflict #143

Problem

Every pull request into a release branch adds to the same two places: a line at the end of CHANGELOG.md's version section, and claims at the end of test/oracles/claims.json. When several pull requests are open at once, each merge leaves the rest conflicting, so each has to merge the release branch back in, push, and run the whole CI again. That is about 10 minutes, the Windows leg being the slowest at 9. With N pull requests merged one after another, that comes to about N²/2 extra runs.

Measured on 2026-10-29, merging the last eight 2.3.0 pull requests (#135 to #142):

• Every merge into release/2.3.0 set the remaining pull requests to DIRTY. The conflicts were in CHANGELOG.md, claims.json and surface-waivers.json. Some pull requests merged the release branch in three times before they were merged.
• Jobs waited up to 7 minutes for a runner when several pull requests pushed their merges at once.
• Two ids were taken twice on parallel branches: claim prefix S01 (feat: Choose, SequenceAsync and TraverseAsync read an async stream #139 and test: read the unread documents for claims #140, renamed to A01 while resolving the merge) and decision record 0115 (feat: an opt-in setting of AddTypeKit writes every value object in place #136 and docs: publish the guides, the READMEs and the API to GitHub Pages with DocFX #138, renamed to 0116). No test caught either before the merge.

The release ruleset doesn't require a branch to be up to date (strict_required_status_checks_policy: false), and the push run on the release branch after each merge tests the combined state. So without these textual conflicts, pull requests that touch different files merge one after another with no re-run.

Proposal

Claims, one file per promise document. Replace test/oracles/claims.json with test/oracles/claims/<document>.json, for example claims/docs-option.json or claims/src-CodoMetis.TypeKit.EntityFrameworkCore-README.json, each holding the claims that quote that document. An id's prefix is tied to its file, so two branches can't take the same prefix. A pull request that adds promises to different documents then touches different files. Readers to change: tools/Oracles/Program.cs (Read<List<Claim>>("claims.json")), OracleCatalogue.Claims, the messages in OracleSurfaceCoverageTests and OracleCatalogueTests, test/oracles/README.md, AGENTS.md's workflow step 7, and docs-query if it reads claims. surface-waivers.json gets the same split if it conflicts as often. It did three times in this run.

Changelog, one fragment per pull request. Each pull request adds changes/<version>/<issue>.md, holding its line or lines. The fragments are joined into CHANGELOG.md's ## <version> section when the release is dated (CONTRIBUTING's "Releasing"), so a released version's section stays the one source. Readers to change or confirm:

• src/Directory.Build.targets (PackageReleaseNotes from the version's section, Packages: show the version's changelog section as NuGet release notes #75). It could read the fragments while the section is undated, or packing could require the joined section.
• .github/workflows/release.yml, which needs a dated section.
• ChangelogTests, PackageReleaseNotesTests and ReleaseWiringTests.
• The links at the tag (feat: a released version's changelog links name its tag #113).
• tools/CiLanes, which needs to classify changes/**.

Order of lines: by issue number, or a field in the fragment. Decide in the decision record.

Sequence numbers. Add a conventions test that fails on two decision records, or two KB entries, with the same number, so a collision fails the merge commit's run rather than going unnoticed.

A decision record states the layout and why, citing this issue's measurements.

Done when

• Two pull requests, each with a changelog line and claims for different documents, both branched from the same commit, merge one after the other with no conflict and no re-sync.
• oracles status and oracles seeds, the NuGet release notes of a packed package, and the release workflow's dry run read the new layout. Each reader's test is seeded and caught.
• A duplicate decision record number fails a conventions test.
• CONTRIBUTING and AGENTS.md describe the layout.