atomic-commits

Atomic Commits

Overview

Take a dirty working tree of uncertain provenance and produce a clean, linear sequence of atomic commits where every commit builds, every commit could be reverted in isolation, and git bisect will land on a meaningful unit when chasing a regression. The agent does not assume it remembers what changed — it investigates, classifies, groups, then commits.

Core Principle: The Bisect Test

Every commit must satisfy this test:

If git bisect lands on this commit alone, can the project still build, run its test suite, and be deployed? And does the commit's title accurately describe a single coherent change?

This produces two rules that govern every grouping decision:

1. Smallest buildable + deployable unit. Do not split a change so finely that an intermediate commit fails to compile, breaks tests, or leaves an import dangling. A new module and its first caller belong together if the caller would not compile without the module.
2. No smaller, no larger. Do not bundle two unrelated improvements just because they touched the same file. Two bug fixes in auth.py should be two commits — bisect cannot tell which one introduced a regression if they ship together.

When the two pull in different directions, prefer the smaller commit and add the minimum scaffolding (e.g., a stub, a no-op default) needed to keep the tree green.

Workflow

Phase 1 — Survey

Before classifying anything, get a complete picture of the working tree.

git status --short
git diff --stat
git diff                       # unstaged
git diff --cached              # staged (rare in this workflow but check)
git log -10 --oneline          # recent history for tone/style of messages

If there are staged changes already, decide whether to keep them as-is (commit first) or unstage to reclassify (git reset HEAD) — but never use destructive resets. When unsure, ask the user.

Phase 2 — Investigate

Treat the diff as code written by someone else. For each modified file:

1. Read the full diff for the file (git diff -- path/to/file), not just the hunks summary.
2. Read surrounding code when the diff alone does not explain intent — function signatures, imports, related call sites.
3. Note the kind of change for each hunk: feature addition, bug fix, refactor, test, docs, formatting, dependency bump, generated/lockfile, config, dead-code removal.
4. Note dependencies between hunks: does hunk B import a symbol introduced by hunk A? Does a test in tests/ exercise a new function in src/?

Write a brief mental (or scratch) inventory: a list of logical changes, each tagged with the files and hunks it spans. This inventory is what gets converted into commits.

Phase 3 — Group

Map the inventory of logical changes onto a commit sequence:

• One logical change → one commit. A bug fix and the regression test that proves it is one logical change and belongs in one commit.
• Order commits to keep the tree green. Foundations first (new module, then its callers; new field on a struct, then code that reads it; new test fixture, then tests using it). Never schedule a commit that depends on a symbol introduced by a later commit.
• Refactors are their own commits. A behavior-preserving rename or extraction should not ride along with a behavioral change. If a feature commit also contains an unrelated refactor, split them.
• Generated files travel with the change that regenerates them. A lockfile bump goes with the dependency change that caused it; a generated client goes with the schema change.
• Formatting-only changes are their own commit, ideally first or last. Mixing a reformat into a feature commit obscures the diff under review and confuses bisect.
• Docs, tests, and code touching the same change live together. Splitting these is over-fragmentation and breaks the "deployable" half of the rule.

If a single file contains hunks belonging to multiple logical changes, plan to use cortex git patch (Phase 4 — hunk-level path).

Phase 4 — Commit

Use the right tool for the shape of the commit.

File-level: cortex git commit

When every hunk in each named file belongs to the same logical change, commit the files whole:

cortex git commit "feat(auth): add OAuth2 device flow support" \
  src/auth/oauth_device.py tests/auth/test_oauth_device.py

This stages the named files in full from the working tree and commits atomically. Use this whenever possible — it's the simplest and safest path.

Hunk-level: cortex git patch --diff

When a file contains hunks that belong to different logical changes, isolate the hunks for one commit via a diff fed through --diff. The files positional is an allowlist — the command will refuse to commit if the diff stages anything outside that list, so name only the files this particular commit should touch.

Two practical ways to produce the diff:

Option A — interactive split via temp file. Generate the file's full diff, edit it down to only the hunks for this commit, then apply:

git diff -- src/auth/oauth_device.py > /tmp/commit-1.diff
# edit /tmp/commit-1.diff in place: delete hunks that don't belong in this commit
cortex git patch "fix(auth): reject device codes after expiry" \
  --diff /tmp/commit-1.diff src/auth/oauth_device.py

Option B — stdin pipe. Build the targeted diff with git diff flags or by piping through filters, and feed via -:

git diff -- src/auth/oauth_device.py \
  | filter-hunks-script \
  | cortex git patch "fix(auth): reject device codes after expiry" \
      --diff - src/auth/oauth_device.py

After each hunk-level commit, the remaining hunks for that file stay in the working tree, ready to be committed (whole or split again) by the next call.

Strongly prefer hunk-level commits over bundling unrelated changes. Two bug fixes in the same file should not share a commit. The hunk-level path is the right tool, not a last resort.

Commit message conventions

Recent history in most Cortex/Nick projects uses Conventional Commits with lowercase types:

• feat(scope): summary — new behavior
• fix(scope): summary — bug fix
• refactor(scope): summary — behavior-preserving change
• docs(scope): summary — docs only
• test(scope): summary — tests only
• chore(scope): summary — tooling, deps, build
• build(scope): summary — packaging, lockfiles

Always check git log -10 --oneline first and match the project's actual style.

Phase 5 — Verify

After the last commit, confirm the result:

git status                  # working tree should be clean (or only contain
                            # changes you explicitly chose not to commit)
git log -N --oneline        # N = number of commits you just made
git diff HEAD~N..HEAD --stat

Spot-check that:

• Every commit's diff stat looks coherent (no surprise files).
• Commit messages name a single change each.
• The order respects build dependencies (foundations before callers).

If a commit looks wrong, do not rewrite history with destructive operations. Either continue with a follow-up fix: commit or escalate to the user before any rebase.

Decision Heuristics

When uncertain about a grouping call, use these defaults:

Situation	Default
Bug fix + its regression test	One commit
New feature + its unit tests	One commit
New feature + integration tests + docs	One commit if tightly coupled; split docs only if substantial
Two unrelated bug fixes, same file	Two commits via cortex git patch
Refactor that enables a feature	Two commits: refactor first, then feature
Lockfile change	Bundled with the dependency edit that caused it
Generated file (codegen, schema, types)	Bundled with the source change that regenerates it
Pure reformatting across many files	Its own commit, kept separate from logic
Dead code removal	Its own commit unless it's directly enabled by the change you're making
Config change + code that reads it	One commit
One commit you're unsure about	Smaller, with hunk-level patch — bisect rewards atomicity

Pitfalls to Avoid

• Don't commit dirty files you didn't author without checking with the user first. If git status shows changes outside the scope you were asked to handle, surface them rather than sweeping them in.
• Don't use git add directly. It bypasses Cortex's safety checks. Use cortex git commit or cortex git patch.
• Don't use git reset --hard, git checkout --, or git stash drop to "clean up" — these destroy uncommitted work. If a state is confusing, investigate rather than reset.
• Don't break the build to make commits smaller. A commit that fails to compile is worse than a commit that bundles two related changes. Add a stub if needed and remove it in a follow-up.
• Don't separate a fix from its test. If bisect lands on the fix and the test is in a later commit, the bisect tool can't validate the fix actually worked at that point.
• Don't reorder commits if the original order had a reason (e.g., a dependency upgrade that unblocks an API change). Keep the natural order; only reorder for build-greenness.
• Don't blindly trust your read of the diff. When unsure what a hunk does, read the surrounding code or run the relevant test. Wrong groupings are hard to repair after the fact.