Header-only rewrites must not touch @Last modified by/time; @Author is never changed unless forced

[Shinrai]

Required behaviour (maintainer decision, 2026-10-04)

1. @Author is the original author and is never changed unless explicitly forced (forceAuthorUpdate). Missing or unrecognised @Author values may still be filled in.
2. @Last modified by and @Last modified time record the last real edit to the file's content. Running fix-headers on a file whose content (everything outside the header) wasn't edited must not change either field, even when fix-headers rewrites other parts of the header: converting the date format (normalizeDateFormat), repairing an epoch, adding the frame/spacing/margin, fixing @Date (fixCreatedDate), filename, project name, copyright year, and so on. Example: converting 2026-03-01 17:59:32 -08:00 to 2026-03-01T17:59:32-08:00 must not change @Last modified by or @Last modified time.
3. When the content was edited, @Last modified by becomes the editor (the identity fix-headers detects for the run) and @Last modified time the edit time. With that in place, forceLastModifiedAuthorUpdate shouldn't be needed for normal use.

Problem today

Any header change restamps @Last modified time. With useGpgSignerAuthor + forceAuthorUpdate + forceLastModifiedAuthorUpdate (the shared CLDMV config), whoever runs the tool also becomes @Author and @Last modified by of every file. Reproduced on 2026-10-04 in CLDMV/slothlet (CLDMV/slothlet#569): a dry run as Jane Contributor with no signing key would rewrite all 1150 headers' @Author and @Last modified by to Jane.

Implementation notes

• "Content edited" needs a definition that works in a writing run. Suggested: compare the file's body (header stripped) with the body at HEAD (git show HEAD:<path>). If they differ, or the file isn't tracked yet, it was edited and gets restamped. If they're the same, keep the existing last-modified values, even if the header itself changes. Outside a git repo, fall back to the current behaviour.
• Consider also using the last commit that changed the body (not only header lines) as the source when a header has no last-modified fields.
• Add tests covering: header-only normalisation with no restamp; a body edit restamping with the runner's identity; @Author preserved for a different runner; forceAuthorUpdate still replacing it; untracked/new files.
• This changes output for every consumer, so it needs a release note.

Related: CLDMV/configs#15 (drop the force options from the shared config).

[Shinrai]

Correction from the maintainer to rule 2: a header-only rewrite still restamps @Last modified time, because the file did change. It must not change @Last modified by.

Change	@Last modified time	@Last modified by	@Author
None	unchanged	unchanged	unchanged
Header only (date format, epoch fix, spacing, fixCreatedDate, …)	now	unchanged	unchanged
Content edited, or new/untracked file	now	the run's identity	unchanged (unless forceAuthorUpdate, or missing)

[Shinrai]

Final rule (maintainer, 2026-10-04), replacing the table above: @Last modified by changes only when the file itself was edited: its content differs from git HEAD, or it's new or untracked. Every change fix-headers makes on its own (timestamp format, epoch, @Date, spacing/frame/margin, filename/project/copyright fields) restamps @Last modified time but keeps @Last modified by. @Author is unchanged unless forceAuthorUpdate is set or it's missing.

Situation	@Last modified time	@Last modified by	@Author
Only fix-headers' own header fixes; file otherwise unchanged	now	unchanged	unchanged
File content edited, or new/untracked file	now	the run's identity	unchanged unless forced
Nothing to change	unchanged	unchanged	unchanged

[Shinrai]

Implemented in 33329b5 on feat/last-modified-content-edits, in PR #128 (#128) into next.

• Content edited means the body (the file with its header and the blank lines after it removed) differs from the body at git show HEAD:<path>, or HEAD doesn't have the file (new, untracked, ignored, or no commits yet). Outside a git work tree there's nothing to compare against, so the recorded editor is kept.
• @Last modified by becomes the run's identity only when the content was edited. Changes fix-headers makes to the header by itself (date format, epoch, fixCreatedDate, time zone conversion, frame/spacing/margin, @Project/@Filename/@Copyright) restamp @Last modified time and keep the recorded editor.
• @Last modified time is restamped whenever the header is rewritten. It also moves once for a new content edit by the editor already recorded: that happens when the body differs from HEAD and the recorded time is older than the file's last commit. Re-runs stay no-ops.
• @Author/@Email are kept unless forceAuthorUpdate is set, and filled in when missing.
• forceLastModifiedAuthorUpdate keeps its old meaning: it writes the run identity on every file. It's documented as not needed for normal use.

Tests are in tests/last-modified-content-edit.test.vitest.mjs. They use real git repos, with the runner identity coming from a temporary GIT_CONFIG_GLOBAL that has no signing key, and useGpgSignerAuthor on. Coverage stays at 100%. The README has a new "Author and last modified" section with the behaviour table. The release note will go in the release-docs PR.

[Shinrai]

Clarification on requirement 2: @Last modified time is restamped whenever fix-headers rewrites a header, including a format-only conversion such as normalizeDateFormat. That is intended: once the header has been rewritten, the time of that rewrite is the file's last modification, so keeping the old value would only make the next run change it anyway.

What a header-only rewrite keeps is the recorded editor: @Last modified by (and @Author / @Email) are unchanged unless the file's content outside the header was edited, or forceLastModifiedAuthorUpdate / forceAuthorUpdate is set. That is what shipped in #128 and what the v2.2.0 changelog and README describe.