Skip to content

fix(record): an edited copy keeps following upstream (#317 item 1) - #368

Merged
willgosnold merged 9 commits into
mainfrom
fix/317-edited-copy-follows-upstream
Oct 26, 2026
Merged

willgosnold merged 9 commits into
mainfrom
fix/317-edited-copy-follows-upstream

Conversation

@willgosnold

@willgosnold willgosnold commented Oct 26, 2026 •

Copy link
Copy Markdown
Owner

Addresses item 1 of #317. The other items stay open.

Problem

Copy an upstream file and commit, so record writes copy skills/a -> skills/b. Then edit skills/b/SKILL.md and commit. record and the commit hook wrote replace skills/b/SKILL.md, a frozen copy. From then on skills/b missed every upstream change to skills/a. An upstream edit to the very line we changed was dropped with no conflict, and status said no problems. The same rule recorded an edited rename of a file that a copy still builds from as delete + add.

Design

An edit to a copy's destination is now a file edit on the destination's path. Its base is upstream's version of the source file, and its ours copy is the edited file.

  • Build. A file edit on a path upstream doesn't have applies in its place in the series, among the structural edits (applyStructure), where the replace it supersedes applied. It edits the upstream file that an earlier copy or move stages at its path. The base must match that file, or the edit is stale. From there on its ours copy is that path's file. A later copy or move of the path reads the edit, as it read the replace on main, while the source and any other copies still build from upstream. A destination edit that no earlier copy or move of an upstream file reaches is gone, and status says so in those words. Once every structural edit applies, a destination edit whose ours copy no staged path reads builds nothing, as after a later hand-written replace or delete of its path that no copy or move reads first. The build doesn't check that edit for stale or conflict markers, so neither status nor the commit hook refuses it.
  • Sync. sync merges the edit with the new upstream source through the existing git merge-file path. A clean merge updates the copy. A conflict leaves markers in ours, sync reports it, and status, build and the commit hook refuse until it is resolved, as for any file edit. sync finds the source with the same structure pass the build uses (applyStructure's upstreamOf, over the pinned files). It reads the other upstreams' pinned files only when some file edit sits under a copy or move destination. It doesn't merge a destination edit that builds nothing, so that edit never gets conflict markers. When base, ours or the new upstream source isn't text, sync can't merge a destination edit. That covers a binary copy, a mode-only edit of one, and a text copy whose source upstream makes binary. sync then keeps ours, as main's replace did. It moves the base to upstream's file, lists the edit in replacedUpstreamChanged and names it on stderr, with how to take upstream's file instead, which is to write it over the output and run record. So the copy keeps building our bytes and status is clean. A file edit on an upstream path keeps main's binary conflict (A binary file edit that conflicts with upstream can't be recovered through sync #374).
  • Record. each writes the destination edit when another output of the same upstream file is still on disk. An edit to the source stays a replace while an unedited copy still builds from it. Once every other output on disk is an edited destination, in an earlier commit or the same one, the source edit is a plain file edit. An edited rename whose source a copy still builds from is move plus file <new path>. Editing the copy again updates its file edit. Deleting the copy takes the file edit out of its change and records a delete, as for a replace. When a later copy or move reads the copy, the file edit stays so that output keeps it, and only the delete is recorded, as main does for a replace. Since the build applies a destination edit in series order, record counts it as a structural edit when it picks a change. It goes only into the change with the copy or move, or a later one, and record <earlier change> refuses and names that change.

DESIGN.md (build order, sync, record) and CHANGELOG.md say the same.

Alternatives

  • A new edit kind, such as file <from> -> <to>. It would name the source in the change, so sync wouldn't need the structure pass. It duplicates the file edit's copies, merge, conflict, show and intent code, and it names the source a second time, which can disagree with the copy line. Rejected.

  • Block entries keyed by output path. Entries cover paragraphs only and are keyed by upstream path, so they can't hold an arbitrary edit to one output. Rejected.

  • Applying every content edit after the structural edits. File edits would all key on output paths, but every recorded move plus file <upstream path> from fix(record): record a renamed output as a move #314 would break, and so would the rule that any change can take a file edit. Rejected.

  • A stored diff applied at build. A 3-way merge succeeds where a diff fails after upstream rewords nearby lines ("Changes store states, not diffs" in DESIGN.md). Rejected.

  • Giving replace a base. replace means ours wins with no merge, for binaries and rewrites. Merging it would change every existing replace. Rejected.

  • Applying destination edits after every structural edit. This PR's first version did that. A later hand-written copy of the destination then built upstream's text, and a move refused as gone, where main's replace built the edit. Rejected for that regression.

  • Merging a destination edit that builds nothing, and ignoring it only in the build. sync would report a conflict and write markers into a file no output reads. Rejected, as is merging it only when the merge is clean, which adds a second rule to sync and still leaves the conflicting case behind.

  • A third Source kind that carries the source path, so the build and the hook could take the destination's mode from upstream. It touches githook.ts for a core.fileMode=false corner. The destination's source stays { kind: "ours" }, and classifyOne reads the change's edit kind, as it already does to tell unadd from unreplace.

  • Recording a binary edit on a copy's destination as a replace, as main did. It fixes a binary copy edited and recorded, but not a text copy whose source upstream later makes binary. That copy still reaches sync's binary conflict, which never moves the base, so status stays stale and sync says Nothing to do. Fixing that needs the sync rule above anyway, and the rule already covers the binary copy. Both build our bytes. Main's replace of a copy's destination gets no replacedUpstreamChanged entry, since upstream has no file at that path, so main froze the binary copy without a word, where the sync rule reports it. Rejected for the second rule it adds.

  • Reporting the kept edit as a conflict while moving its base. The summary would count a conflict with no markers to resolve and a clean status. Rejected, as are rewriting the edit to a replace during sync (a new kind of sync write) and taking upstream's bytes when ours differs from base only in mode (a second binary rule that upstream paths don't have).

Tradeoffs

  • A destination edit sync can't merge as text doesn't follow upstream, as main's replace didn't. sync says so on stderr and in replacedUpstreamChanged, which the patchbook-update skill already handles. A mode-only edit of a binary copy keeps our old bytes with our mode, rather than taking upstream's new bytes. To take upstream's file, write it over the output and run record.
  • The base is the raw upstream file. When the source also has a file edit or block entries, the copy keeps that text as it was when you edited the copy. Upstream's later changes still merge in, but later changes to the source's own edit or entries don't reach the copy. Before this PR nothing reached it.
  • The destination's mode comes from its ours copy, as for any output upstream doesn't have. sync moves upstream's mode into both copies, so an upstream mode change still reaches the output. Under core.fileMode=false, the hook doesn't stage that new mode for the destination the way it does for an output built straight from upstream.
  • A later structural edit of the destination's own path wins over its file edit, as it wins over a replace on main and over a file edit on an upstream path. A hand-written replace of the destination in a later change builds the replacement, and a delete removes the output. Then nothing builds from the file edit, so sync leaves it alone, and an upstream change to the line it edits doesn't stop the build, as on main. record never writes either while the file edit is there. If you later remove that hand-written replace or delete, the file edit is stale until upstream next moves, because sync at an unchanged pin does nothing. The next sync merges it correctly. Main has the same dead end for any file edit whose base is behind the pin, such as one merged in from a branch.
  • A copy recorded as a replace before this PR stays a replace. Editing it again updates the replace.
  • Renaming an edited copy is still delete plus add, as it was with the replace (Renaming or moving an edited copy freezes it again #373).
  • A copy destination's missing, stale and gone problems read changes/<name> file <path>, as a copy's replace did on main, and a missing copy says which one: invalid changes/b-edit file skills/b/SKILL.md: its ours copy is missing. A file edit on an upstream path keeps main's wording, its base or ours copy is missing.

Proof

All numbers are at the head, 5be46d3.

  • Tests. The first commit adds or changes 10 e2e tests. On 87e3dab, 9 of them fail with replace or delete + add. The tenth edits only the source, which stays a replace, so it passes on both. Commit 88a38cd adds 5 more, which all fail on 3505d53. They cover a later hand-written copy and move of an edited copy, deleting an edited copy that a later copy reads, record refusing a destination edit into a change before its copy, and the gone wording. Commit 8f02e9a adds the sync test for a destination edit with a missing base copy. Commit f30f940 adds 3 more, which all fail on 8f02e9a. A hand-written replace and a hand-written delete of an edited copy each build after upstream changes the line the copy's edit changed. Sync merges nothing into the superseded edit, and status is clean. The commit hook takes a hand-written replace over a copy whose superseded edit holds sync's conflict markers. f30f940 also adds a sync to the deleted-copy test, so an edit a later copy reads still merges. Commit accb1da adds 4 more. In 3 of them a binary copy has its bytes or its mode edited, or a text copy's source turns binary. Each fails on f30f940 with sync's 1 conflicts. Copy, edit, record, a change to the source upstream and a sync then build our bytes, and status is clean. The text copy then takes upstream's file once it is written over the output and recorded. The fourth, a mode-only edit to a text copy, passes on both and is there for coverage. Commit 5be46d3 adds 4 more and changes 1. They cover a copy's missing base copy, missing ours copy, both missing, and a base that differs from its source, in status, build and status --json, and it changes the gone test to the new wording. All 4 new ones and the changed one fail on accb1da, which didn't name the change. The classify units state the destination rule.
  • Targeted runs. bun run typecheck exits 0, and test/units.test.ts passes 331 of 331. bun test test/e2e.test.ts -t "copy|move|replace|record|sync|track|binary|missing" passes 835 of 835.
  • Live CLI. The owner's pb-sandbox driver runs record, the commit hook, sync, status and build against clean clones. 14 of its 55 expectations fail on 87e3dab, and none fail at 5be46d3. Its journeys cover the hook and direct record, an overlapping upstream edit (conflict, refusal, resolution), a source edit after the copy edit, an edited rename, deleting the edited copy, and a copy already recorded as a replace.
  • Live verification lane. 27 journeys in the fork and folder layouts make 1183 assertions, and 1173 pass. The driver is round 2's, with only the superseded journeys' sync assertion set to main's 0 of ours merged cleanly, 0 conflicts. Against the accb1da run, the four J_missing_* status rows now pass and every other row is unchanged. The 10 failures are the known ones. The renamed copy fails twice (Renaming or moving an edited copy freezes it again #373). The 4 superseded sync rows still expect the conflict that round 4 removed, and main prints 0 conflicts too. The superseded upstream-path control fails four times, and main refuses the same way (A conflicted file edit that a later replace supersedes still blocks build and status #378).
  • Audit probes. The independent audit's probes from rounds 1 and 2 make 29 transcripts. Once hashes and sandbox paths are normalized, 27 match f30f940. The other two are binary and binaryrecover. In both, sync now keeps our bytes and status exits 0. In binary, build exits 0 too. In binaryrecover, last-sync.json lists the copy in replacedUpstreamChanged. Their new expectation failures are round 1's expectations of a refusal and a binary conflict. binarymain, a binary file edit on an upstream path, is unchanged (A binary file edit that conflicts with upstream can't be recovered through sync #374). handcopy and handmove carry the edit. twice matches main, where the later replace builds.

The drivers and transcripts are in the #317 owner folder of this run.

🤖 Generated with Claude Code

willgosnold and others added 6 commits October 26, 2026 19:05
These fail on main: an edit to a copy's destination records as a
replace, so the copy stops following upstream, and an edited rename of
a file that a copy still builds from records as delete + add.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An edit to the destination of a copy or move of an upstream file, while
another output of that file is on disk, now records as a file edit on
the destination's path whose base is the upstream file. The build
applies it after the structural edits, so it builds that output alone,
and sync merges upstream's changes to the source into it, reporting a
conflict as for any file edit. It was a replace, which froze the copy.

- assemble: a file edit on a path upstream doesn't have waits for the
  structural edits and edits the upstream file a copy or move stages
  there (editedUpstream); otherwise it is gone, as before.
- sync: a destination file edit merges with that upstream file, found
  with the same structure pass at the pins, only when some file edit
  sits under a copy or move destination.
- record: an edited rename whose source a copy still builds from is a
  move plus a file edit on the new path. An edit to the source is a file
  edit once every other output on disk is an edited destination.
  Re-editing the copy updates its file edit, and deleting it drops the
  edit and records a delete. A replace no longer deletes block entries;
  a destination file edit does once nothing reads them.
- tests: the source-edit and vendor hook tests use inputs that don't
  touch upstream's line or a long change name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… comments (#317)

The no-comments pass took out the comments this PR added or rewrote.
`each` now says the rule in names (isDestination, others,
nothingReadsEntries, editedDestination), and destinationSources takes an
atPin callback in place of the upstream and its files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…edit (#317)

A hand-written copy or move of a copy's destination after its file edit
read upstream's text or refused as gone, where main's replace built the
edit. Deleting the edited copy dropped the edit from the copy that reads
it, and record wrote the edit into a change before the copy. A gone
destination said upstream no longer has it, though upstream lost only
its source.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#317)

A file edit on a copy's or move's destination applied after every
structural edit, so a later copy or move of the destination read
upstream's text or found nothing to move. It now applies in its place in
the series, where the replace it supersedes applied: a later copy or
move reads the edit, and the destination still has a base and follows
upstream. applyStructure reports the upstream file under each such edit,
and the build and sync both read it.

record counts a destination edit as structural when it picks a change,
so it never goes into a change before its copy, and deleting an edited
copy that a later copy reads keeps the edit, as main does for a replace.
A gone destination now says no earlier copy or move reaches it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…th the controlled message (#317)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…te supersedes (#317)

A hand-written replace or delete of an edited copy left the copy's file
edit in place with nothing building from it. Sync still merged it, so an
upstream change to the line it edits wrote conflict markers into an ours
copy no output reads, and build, status and the commit hook refused. Main
builds that case, since a replace never merges.

applyStructure now names each destination file edit whose ours copy no
staged path reads once every structural edit applies. Sync doesn't merge
it, and the build skips its stale and conflict-marker checks, so the
build writes the replacement or omits the path. An edit a later copy or
move reads, even after its own delete, still merges. A superseded file
edit on an upstream path keeps main's behavior.

CHANGELOG and DESIGN say a deleted edited copy keeps its edit while a
later copy or move reads it, and that a source edit is a replace only
while an unedited output still builds from it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Recording an edit to a binary copy wrote `file <dest>`. Once upstream
changed the source, sync reported a binary conflict, left the base
behind and said "Nothing to do" on the next run, so status and build
refused with no way out but hand-editing CHANGE.md. Main recorded a
`replace` there, which kept building our bytes.

When base, ours or upstream's file of a destination's file edit isn't
text, sync now keeps ours as the replace did, moves the base to
upstream's file, lists the edit in replacedUpstreamChanged and names it
on stderr. That covers a binary edit, a mode-only edit of a binary copy
and a text copy whose source upstream makes binary. A file edit on an
upstream path keeps main's conflict (#374).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…stination's problems (#317)

A copy destination's missing-copy, stale and gone problems dropped the change name that main printed for a copy's replace. They now report as the change's file edit, and the missing-copy detail says which copy is gone.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@willgosnold

Copy link
Copy Markdown
Owner Author

Root countersign: independent verification PASS covering exact head 5be46d3 against main 598249d. Full lanes and a design review at 3505d53 and 8f02e9a, then focused verifiers at accb1da and 5be46d3, with all six CI checks green at this head. I corrected one test count in the description, and the head is unchanged. This authorizes an exact-head squash merge of 5be46d3 only.

@willgosnold
willgosnold merged commit 3e3abd8 into main Oct 26, 2026
6 checks passed
@willgosnold
willgosnold deleted the fix/317-edited-copy-follows-upstream branch October 26, 2026 20:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant