Agent Edit Scope

The complaint this comes from

> *"Cursor keeps re-writing many files in my project for no apparent reason with the same > content."*

That thread has siblings in every agent forum. You ask for one change and get a diff touching forty files, most of them the same code with the imports reordered and the quotes flipped.

It is not a correctness bug, which is why nobody fixes it. It is an attention bug, and it compounds:

• Review capacity is finite. Thirty-nine cosmetic files hide the fortieth that matters — and
• reviewers who learn a diff is mostly noise stop reading diffs.
• git blame now attributes every line of those files to the agent's commit, so the next person
• debugging them loses the history that would have explained the code.
• Every touched file is a merge conflict for anyone working in parallel.

  assessChangeset(edits);
  // { noOpRatio: 0.75, requiresReview: true,
  //   reasons: ["3 of 4 files changed nothing — cosmetic noise hides the files that did
  //             change, and reviewers who learn a diff is mostly noise stop reading diffs"] }
  
  dropNoOps(edits);  // just the files that actually changed

Substantive is the default

Calling a file "unchanged" means normalising formatting away — and normalise too far and you hide a real change. So every rule is **named, individually enableable, and must fully explain the difference**. A file is never called cosmetic because a similarity score looked high enough.

| rule | default | what it forgives | |---|---|---| | whitespace | on | trailing space, indentation, final newline | | line_endings | on | CRLF vs LF | | import_order | off | import lines reordered but identical as a set | | identical | on | byte-for-byte |

import_order is off by default because sorting a set of imports is safe and adding to it is not — a test asserts an added import survives as substantive even with the rule on.

This is the same discipline clause-span-grounding applies to contract text, for the same reason: a verifier that normalises aggressively stops verifying.

Deletion-heavy is its own verdict

An agent asked to "clean up" that removes eighty lines and adds two reads identically to a small refactor in any summary that counts files. It gets its own verdict so it cannot hide in one.

Scope

  assessChangeset(edits, { allowedPaths: ["src/**"], protectedPaths: [".github/**"] });

protectedPaths is checked even when the declared scope allowed it. An agent that decides your CI config needs editing to finish the job is exactly the case you want stopped, and "the task said so" is not reassurance when the task was written by the same agent.

What it does not do

| not included | why | |---|---| | Reading git, running diffs, blocking commits | pure functions over before/after strings — wire it into whatever hook you like | | Parsing code / AST comparison | a parser per language is a different product; this is textual and says so | | Judging whether the change is correct | only whether it is a change | | Reverting anything | it reports; you decide |

Textual comparison means a semantically-identical rewrite that reorders whole functions reads as substantive. That is the safe direction to be wrong in.