Cross-track commit sweep handling¶
When work for one active-work track gets
accidentally swept into a commit authored under a different track's
[track: ...] trailer, do not rewrite history. Annotate forward.
Rule¶
Once a commit lands on main, its [track: ...] trailer is immutable.
Rewriting (rebase, amend, force-push) trades a small audit gap for a
larger one — silent history mutation breaks signed-commit verification,
invalidates downstream clones, and makes the original mistake harder to
learn from. The audit trail is more valuable than a tidy trailer.
Annotation convention¶
Add a follow-up empty commit on main whose message carries:
- A
[sweep-of: <sha>]trailer pointing at the offending commit. - A per-file ownership list naming the correct track for each file the original commit shouldn't have touched.
- The trailer for the annotating commit's own track (typically whichever track is doing the bookkeeping).
Example shape:
chore(work): annotate cross-track sweep in 6c9b171
Files swept under track foo that belong to track bar:
- path/to/file-a (track: bar)
- path/to/file-b (track: bar)
[sweep-of: 6c9b171]
[track: cross-track-commit-sweep-policy]
Signed-off-by: ...
git commit --allow-empty is fine — the body IS the artifact.
active-work.yaml linkage¶
Both the originating track and the receiving track add a commits_swept
entry pointing at the original commit + the annotation commit. This
makes the bookkeeping queryable from either side.
Going-forward mitigation¶
Stage explicitly. git add -A and git add . are how sweeps happen.
Prefer git add -- <pathspec>, then git diff --cached --stat before
every git commit — if the file list doesn't match the track scope,
unstage and split.
A pre-commit hook that warns on cross-scope staging is separate work (not yet shipped); for now this is honor-system, like the rest of the ADR 0006 trailer discipline.