fix(ratchet): a new file inherits old-name lines only from files the change deletes

[eldad-caura-ai]

What

A line in a file the change adds now counts as moved only if a file the change deletes held the same text. Deletions from files that survive no longer pay for it, so the line is charged as new even when the repo-wide count of its text didn't rise.

• New and deleted files come from git diff --name-status --no-renames. A renamed file is a deletion plus an addition, so it inherits from its own source however heavily it was edited, with no similarity threshold involved.
• New files are visited first. Otherwise an existing destination of the same text could spend the budget on what is really the move, and both files would fail.
• The failure text explains the rule. A failing new file whose text the repo already had is labelled (0 -> 1, new file: inherits only from deleted files).

Why

This closes the "new prose" gap from the rebrand close-out (action 7: treat old names in new files as new, even when the same text exists elsewhere).

Copies already failed, because the repo-wide count goes up. What was left was the move excuse. A new page or module that repeated a common branded line, such as an install command or a URL, passed whenever the same change deleted an identical line anywhere else. _minted's docstring calls that coincidence undecidable by counts. For new files it no longer has to be decided.

The cost

A line moved into a new file out of a file that stays (a split or an extract) now fails. #882 excused that because no marker reason described a move. For a new file, either a marker states the case truthfully (legacy-name-ok, legacy-name-floor), or the line is unrenamed debt being written into new prose. Whole-file renames, including heavily edited ones, still pass.

Testing

• Suite: tests/test_legacy_name_ratchet.py passes, 210 tests, run the way the required workflow runs it (a two-file checkout, Python 3.13, pytest>=9.1.1,<10.0).
• Five new tests, each confirmed to fail when the part of the rule it guards is removed:
  • test_a_move_into_a_new_file_from_a_file_that_stays_is_an_addition: fails if the rule is removed.
  • test_a_new_file_inherits_from_the_file_this_change_deletes: fails if new files can't inherit.
  • test_a_deleted_line_is_inherited_once: fails if inheritance doesn't use up the deleted line.
  • test_a_new_file_takes_the_charge_not_an_existing_destination (both sort orders): fails without the new-files-first ordering.
• Eight existing tests modelled "a move between existing files" with a destination the change created. They now commit the destination first, which is what their docstrings describe. Their assertions are unchanged.
• Replay: I replayed the last 40 first-parent commits of caura main and caura-enterprise dev under the old and the new script. Every commit gets the same verdict. A spot check confirmed both versions really ran.
• Lint and gates:
  • ruff check (repo config) is clean on both files.
  • ruff format --check --isolated passes on the script (test_the_engine_stays_formatter_stable).
  • The legacy-name ratchet finds no new lines, and the do-not-touch sentinel reports all 35 strings survive.

Rollout

The org-wide required check runs the engine from ratchet-stable, which is at ccd11eb8 (2026-09-16). That branch also lacks #1732, which landed on 2026-10-01. Neither change applies to other repos until ratchet-stable is moved forward after this merges. It's a fast-forward, since ratchet-stable is an ancestor of main.

🤖 Generated with Claude Code

[github-actions]

🤖 Review by Claude Code

Claude Code Review ✅ No issues found.

---

Reviewed by claude-sonnet-5-5 · cost $0.22409225

[eldad-caura-ai]

@erni-a please arprpveo