# .gitattributes — merge-driver policy (the "never silently union a source-of-truth" rule)
#
# WHY THIS FILE EXISTS: two sibling branches merging in sequence collided on docs/STATUS.md and
# CHANGELOG.md (both carry a single "current test count" scalar that each branch rewrote). The tempting
# "fix" is `merge=union`, which auto-keeps BOTH sides with NO conflict marker. That is SAFE only for a
# strictly monotonic-append log, and a SILENT-CORRUPTION TRAP for any file where two values must
# reconcile to ONE value — it would ship "1141 pass" AND "1144 pass" with nobody alerted.
#
# THE RULE:
#   - A file where divergent edits must reconcile to a single value (STATUS.md, CHANGELOG.md — both
#     carry the live test count + gate-pass claims in their headers) => normal 3-way merge (`merge=text`).
#     A genuine conflict SHOULD surface a marker so a human reconciles the scalar by hand. NEVER union.
#   - A file that is strictly append-only / per-version frozen and is never co-edited across branches
#     (per-version docs/releases/RELEASE_NOTES_*.md) => `merge=union` is acceptable.
#   - Code is ALWAYS 3-way (git's default); never union source.
#
# DO NOT add `CHANGELOG.md merge=union`: this repo's `## [Unreleased]` header carries reconcilable
# scalars (the test count, "all three gates pass"), so union would silently ship contradictory state.
# (The CI `merge-hygiene` gate is the hard backstop — a leftover marker can never reach main either way.)

# --- single-source-of-truth docs: pin to 3-way so divergent scalars MUST surface a conflict marker ---
docs/STATUS.md   merge=text
CHANGELOG.md     merge=text

# --- per-version frozen release notes: append-only, never co-edited across branches → union is safe ---
docs/releases/RELEASE_NOTES_*.md  merge=union
