Parallel PRs serially conflict in CHANGELOG.md + artifacts/requirements.yaml (every REQ/changelog addition collides)

[avrabe]

Friction hit repeatedly this session while landing several one-REQ-per-PR changes (the dogfooding workflow). Every PR that adds a CHANGELOG entry and a REQ artifact conflicts with every other such PR, forcing a manual rebase+resolve each time — I resolved this on #419 and #421 in the same hour.

Why

1. CHANGELOG.md — every PR inserts its entry at the top of ## [Unreleased], so any two PRs touch the same lines → guaranteed conflict. Structural and unavoidable with normal merge.
2. artifacts/requirements.yaml — REQs added mid-file (e.g. "after REQ-160") collide when two PRs target the same anchor. rivet add itself appends at EOF (mutate::append_artifact_to_file), which is better, but two EOF-appends still conflict on the final lines, and hand-authored inserts (Edit) are worse.

Suggested fixes

• CHANGELOG.md → merge=union via .gitattributes (git's built-in union driver keeps both sides' added lines — exactly right for an append-only changelog). Near-zero risk; eliminates the most frequent conflict. (Implementing this now — small PR.)
• artifacts/requirements.yaml — either (a) also merge=union (safe as long as additions are append-only blocks; risk is duplicated lines if two PRs edit the same existing artifact — acceptable for an additive log), or (b) document "append new REQs at EOF / always use rivet add, never insert mid-file". Recommend (b) as guidance + consider (a).
• Longer-term: rivet add could write each artifact to a per-id or per-sprint file (sharded sources) so parallel adds never touch the same file — the cleanest structural fix, but a bigger change.

Found while running the hourly dogfooding loop (the loop itself is the heaviest generator of these conflicts).

[avrabe]

Triage pass (issue-triage agent run 2026-06-03):

Safe half merged. PR #423 (REQ-164) landed the .gitattributes CHANGELOG.md merge=union driver — the most-frequent half of the friction described here is gone. The PR explicitly punts artifacts/*.yaml merge=union ("union-concatenating conflicting YAML hunks can silently produce malformed/misordered YAML"), which is the right call.

What's still open in this issue body, and not yet AC'd:

1. Documenting the requirements.yaml policy — the body recommends (b) "append new REQs at EOF / always use rivet add, never insert mid-file" as guidance, and chore(git): union-merge driver for CHANGELOG to cut parallel-PR conflicts (REQ-164, #422) #423's description encodes that intent already, but there's no docs change yet. Tractable as a small focused docs PR.
2. Longer-term: per-id / per-sprint sharded artifact sources — body itself flags this as longer-term and behaviour-changing for the artifact layout. Needs its own design issue and is well out of one-PR scope.

For autonomous pickup on item 1, could you lift it into an explicit ## Acceptance Criteria block? Shape:

## Acceptance Criteria
- [ ] `docs/contributing.md` (or `AGENTS.md` / `CLAUDE.md` as you prefer) adds a "Parallel-PR friction" section stating: new REQs are appended at EOF of `artifacts/requirements.yaml` — use `rivet add` (which already EOF-appends via `mutate::append_artifact_to_file`); never insert mid-file
- [ ] The same section notes the CHANGELOG `merge=union` rule from #423 so contributors understand why their CHANGELOG conflicts went away
- [ ] (Optional but cheap) `rivet validate` adds an *advisory* lint that flags hand-authored mid-file REQ insertions in a PR diff (severity: info), so the policy is self-enforcing without breaking history; gate behind a flag if implementing this might be noisy
- [ ] Commit trailer: `Refs: REQ-164` (the existing CHANGELOG REQ) or a new doc REQ if you'd prefer; `rivet validate` PASS

For item 2 (sharded sources), recommend a separate issue when you're ready to design it — explicit non-goal on this one.

Process side-rail (same as the other open triage threads today): https://pulseengine.eu/blog/ is still HTTP 503, so no PR will land from this run regardless — the binding workflow guidance can't be consulted. Item 1 above is queued for the first run after the blog returns, once the AC is added.

If you'd rather close this issue now that #423 captures the practical fix, that's also fine — say the word and I'll re-triage in the next pass.

Not implemented this run.

---

Generated by Claude Code — issue-triage agent run 2026-06-03.

---

Generated by Claude Code

[avrabe]

Fresh data point: hit this again this hour. PR #454 (REQ-184) and #455 (REQ-185) were branched in parallel; each appended its REQ at the EOF of artifacts/requirements.yaml. After #454 merged, #455 needed a manual rebase to resolve the requirements.yaml conflict (both inserted at the same EOF). It's mechanical (keep both blocks) but it's a recurring tax on every pair of in-flight PRs that file a REQ — exactly what this issue describes. CHANGELOG.md is already handled via merge=union in .gitattributes (REQ-164); the same union-merge driver would likely absorb requirements.yaml EOF-appends too, though it was previously deferred as risky for YAML. Worth re-evaluating, or an alternative (one-REQ-per-file, or a post-merge re-sequence).

[avrabe]

Fresh recurrence (this hour): PRs #467 (REQ-195) and #469 (REQ-196) were both in flight; each EOF-appended its REQ to artifacts/requirements.yaml. #467 merged first, then #469 failed with "Pull Request has merge conflicts" and needed a manual rebase (keep both blocks) to land.

Notable pattern across every recurrence I've hit (REQ-184/185, 195/196, …): the conflict is always the same shape — two new list items appended at the same EOF, never an edit to an existing REQ. That's precisely the case a merge=union driver resolves correctly (concatenating two appended YAML list items is always valid YAML; the "risky for YAML" failure mode — two PRs editing the same region — would conflict under union too, i.e. no worse than today). CHANGELOG.md already uses merge=union (REQ-164) for the identical append-only pattern.

Not implementing unilaterally since the maintainer flagged YAML-union risk, but the evidence is now strong that the append-only REQ case is exactly union's safe case. If union still feels too broad, the narrower alternative is one-file-per-artifact (e.g. artifacts/requirements/REQ-NNN.yaml) so appends never share a region.

[avrabe]

Triaged from the dogfooding loop — and acted on item 1.

Item 1 (document the EOF-append policy): done in PR #489. Implemented your Acceptance Criteria as an AGENTS.md "Parallel-PR friction" section: append new artifacts at EOF / use rivet add / never insert mid-file; explains the CHANGELOG merge=union (REQ-164) and why requirements.yaml deliberately doesn't use union; documents the mechanical keep-both resolution. Made it a docs-only change with no new REQ on purpose — filing a REQ would append to requirements.yaml and cause the very collision being documented; per your AC it Refs: REQ-164.

Fresh recurrence (more evidence): this bit me again last hour — PR #487 (REQ-206) went DIRTY because main had advanced (REQ-200/#473) and both appended at the requirements.yaml EOF. Mechanical keep-both rebase fixed it. Same shape as every prior recurrence (REQ-184/185, 195/196, …): always two appended list items, never an edit to an existing artifact.

On the requirements.yaml merge=union question (still your call): I did not implement it — you flagged YAML-union risk and I'm respecting that. But the evidence is now very strong that the risk case and the benefit case are disjoint: union auto-concatenates only non-overlapping hunks (two EOF appends → always-valid YAML), and two PRs editing the same artifact's lines would still conflict under union exactly as today — so union is strictly better for the append case and no worse for the edit case. If the residual fear is a pathological same-line edit slipping through as duplicated keys, rivet validate + YAML-lint in CI would catch it. Happy to ship the one-line .gitattributes rule if you want it; leaving the decision to you.

Item 2 (structural fix): filed as a separate design issue per your earlier recommendation — see below.