Skip to content

feat(repo-builder): three-way merge modified managed paths on update - #330

Merged
possiblyneal merged 3 commits into
mainfrom
possiblyneal/update-eligible-repos
Nov 19, 2026
Merged

possiblyneal merged 3 commits into
mainfrom
possiblyneal/update-eligible-repos

Conversation

@possiblyneal

@possiblyneal possiblyneal commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Intent

Closes #329
Closes #328

A template update stopped each destination for a hand merge whenever a managed file carried both the template's change and the destination's own edits. The root CLAUDE.md always does, so the carry to 83ece89 stopped 20 of 21 repositories at reconcile. update.py apply now three-way merges such a path (old payload at the recorded commit, the destination's file, the new payload at the target). A clean merge lands staged at the payload's mode as action merge. Overlapping edits stay under left as conflicted, with nothing written. The pull-request body and the several-destinations report name merged paths from the records instead of leaving a slot.

Read first

  • apps/repo-builder/src/scripts/update.py:105: merge_payload, which refuses symlinks and handles the exit codes (0 clean, 1–127 conflicts, anything else unmergeable)
  • apps/repo-builder/src/scripts/update.py:456: where apply tries the merge, limited to modified paths with status M
  • apps/repo-builder/src/scripts/update.py:729 and :1257: Decisions and Preserved/Merged/Conflicted rendering
  • Mechanical: write_payload split into write_content, so the merge reuses its mode, symlink and stage handling; prose updates in references/update.md, references/reporting.md and apps/repo-builder/CLAUDE.md

Decisions

  • Every modified managed path is merged, not only CLAUDE.md, because one mechanism covers both. On this update's 22 hand merges, git merge-file reproduced 21 byte for byte, both .pre-commit-config.yaml merges among them. The one conflict, possiblyneal/template's own CLAUDE.md, needed a decision anyway.
  • A line merge (git merge-file) over a section-aware Markdown or YAML merge, because the stdlib and git already cover it, and a conflict stays the Operator's.
  • A merge git merge-file cannot run (binary) stays modified, not conflicted, so a tool failure never reads as a content conflict.
  • A symlink on either side (destination path, or payload mode 120000 at either commit) stays modified with nothing written, because git merge-file reads through a link and would replace it with a regular file. Found in review.
  • Adds, deletions and renames against a changed destination stay left: there is no three-way base for them.

Out of scope

  • .github/, which is still replaced whole.
  • Merging in retrofit or generate flows.

Verified

  • uv run pytest apps/repo-builder/src/scripts/tests/test_update.py → 95 passed (clean merge, conflicted, binary, symlink, mode, ignored path, pr-body, report and run → ready cases); the symlink case fails without its guard
  • scripts/check at c6e17b9 → exited 0: 0 FAIL, 0 unavailable, 5 not-applicable, 26 pass
  • Manual replay of git merge-file over the 22 left paths of the 83ece89 carry → 21 identical to the committed hand merge, 1 conflicted (2 hunks)

Not verified

  • No live update.py run against real destinations since this change: none is behind the template, so the next template commit's update is the first real run.

Merge danger

Door: two-way: a revert restores everything

Blast radius: update.py apply, run, pr-body and report, and the /repo-builder update flow that reads their output. The apply JSON gains action merge and reason conflicted. generate.py imports only update.py's copy proof and slot marker, both unchanged.

neal added 3 commits November 19, 2026 10:52
A template update stopped for a hand merge whenever a managed file carried both
the template's change and the destination's own edits, though the two usually
touched different lines. apply now runs git merge-file over the old payload,
the destination's file and the new payload. A clean merge lands staged at the
payload's mode as action merge, overlapping edits stay left as conflicted, and a
merge that cannot run (binary) stays left as modified.

pr-body Decisions and the report's Preserved/Merged/Conflicted line name merged
paths from the records instead of leaving a slot.

Generated-By: claude-sonnet-5-5
…ed managed path into possiblyneal/update-eligible-repos

Generated-By: claude-opus-5-5
A symlink on either side of a modified managed path was read through
and replaced by a regular file holding the merged target text. The
merge now returns modified, writing nothing, when the destination path
is a symlink or the payload's mode at the recorded or target commit is
a symlink.

Also names the merge outcome separately from the left reason in
apply_update, and computes each change's path once.

Generated-By: claude-opus-5-5
@possiblyneal possiblyneal added the code-reviewed Multi-axis code review passed label Nov 19, 2026
@possiblyneal

Copy link
Copy Markdown
Owner Author

Code review: standard scan, clean.

Axes: Standards+Spec, Correctness/Logic

Reviewed-Head: c6e17b9

@possiblyneal
possiblyneal merged commit f42bf3b into main Nov 19, 2026
7 checks passed
@possiblyneal
possiblyneal deleted the possiblyneal/update-eligible-repos branch November 19, 2026 16:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

code-reviewed Multi-axis code review passed

Projects

None yet

1 participant