Working & atomic commits

An agent produces a lot of change fast. The thing that keeps that from becoming a blur is the commit discipline — four rules from the workflow contract (AGENT.md):

1. One commit per meaningful step, present tense, imperative subject.
2. Reference the ticket id in the body, not the subject.
3. Never commit unrelated changes together.
4. Do not commit or push unless the work builds and its tests pass.

What that looks like for real

The actual 4Notice history, newest first — thirteen days of app in eleven lines:

1fadaeb App icon and launch screen
9903739 Localize the UI into seven languages
2b452ae 14-day trial, then read-only; one-time unlock via StoreKit 2
d846a0e watchOS app: the four notes as read-only pages
1c10e02 Widgets for macOS and iOS, one per note
9469f74 macOS: quick access from the menu bar
15a742a Per-device font family and size
db22347 iPhone: one note at a time, swipe, pin as start note
b770b64 Sync notes through NSUbiquitousKeyValueStore with a size budget
422f971 Add rich text notes with a small format bar
ddcfa94 Add tickets N1–N13 from the basic app plan

You can read the product’s story without opening a single diff. Each subject states an outcome; each maps to a ticket. And inside:

commit 422f971
Add rich text notes with a small format bar

Notes hold an AttributedString with codable intent attributes (bold,
italic, underline, heading); fonts are derived for display and never
stored. Format bar per note: B/I/U/H, bullet and checklist prefixes.

Ticket: n2-rich-text-editor

The body earns its keep twice: it records the design decision (intent attributes, fonts derived, never stored) where the next reader will look for it, and the Ticket: line ties the change to the scope, acceptance criteria, and Q&A that produced it. Commit → ticket → plan: the full why-chain of any line of code, three hops, all in the repo.

“Atomic” is a scope statement

Atomic doesn’t mean small — the widgets commit touches many files. It means one meaningful step: everything in the commit serves one ticket’s scope, and nothing else rode along. The payoffs are practical: a revert removes exactly one feature; a bisect lands on one decision; a review reads one thought.

The two rules that protect this when an agent is doing the driving:

• No drive-by fixes. Spotted an unrelated bug mid-ticket? It becomes a ticket (or at least its own commit) — never a stowaway.
• Green before commit. Rule 4 means the history has no “WIP, tests broken” states — every commit is a place you can check out and build. For 4Notice that’s sh scripts/test.sh before every commit, the same script the toolbar’s ⌘U runs.

The second ledger

Commits track the code; the ticket history tracks the process — an append-only JSONL per ticket where the agent logs station moves, recorded answers, and skill runs (details). When something looks odd later, the two ledgers cross-check each other: what was done, and what was decided while doing it.

With the working rhythm in place, the next chapters add leverage: importing skills so the agent doesn’t relearn solved problems — and exporting your own.