lanework/DESIGN/14-git-operations.md

Git Operations — Extracted Conclusions

Tier scope: Lanework Pro (12-editions.md). This doc extracts the settled conclusions from the pathfinder's git-operations analysis (../../Kanban/AI-ANALYSIS-git-operations.md, 2026-07-23) so the git milestone has a citable in-repo source. It resolves the design corpus's outstanding tbd — the git-operations doc extraction the Implementation board's root index names as one of two TBDs graduating into work items. The source file catalogued issues and deliberately made no decisions; the decisions were made in 06-history-undo.md and 07-sync-collab.md, and this doc records which of the source's conclusions those docs build on — and which of its leanings later design deliberately settled otherwise. Issue tags (A1, C3, …) are the source file's.

The forward-restore model (C3, C9) — the load-bearing extraction

Every restorative operation moves history forward. Nothing the app does ever rewrites a published commit: no reset, no force-push, no revert-by-rewrite.

• Undo (⌘Z) and redo (⇧⌘Z) restore earlier states as new forward commits ("Undo: ⟨subject⟩"). Reset-based undo is forbidden once any second observer exists — a remote, another machine, an agent reading the repo — because it rewrites history that observer may already have seen (C3). And the observer assumption is not optional: agents-as-concurrent-editors is a product requirement, so the safe case for reset (a never-pushed, never-read local tip) is never provable. Forward-only sidesteps the entire class.
• Under sync, forward-only undo makes an undo just another change for the sync loop to carry — nothing special, no divergent realities for anyone who saw the abandoned state (C9). Reset-based undo would instead manufacture divergence with every ⌘Z.
• The one deliberate rewrite in the app is pull's rebase of unpushed local commits (07-sync-collab.md) — local-only history, never published, rebased so the shared trail stays linear. Published history is never touched, by anyone, for any reason.

This is the conclusion 06-history-undo.md's "Undo never rewrites history" rule builds on, and the reason a rewritten remote (an outside agent force-pushed) is treated as fresh divergence to merge — never mimicked locally, never force-pushed back (B7).

Persistence across relaunch (C8) — as later design settled it

The source left C8 open between an in-memory stack that dies with the app and a git-enabled "restore to any point" browser. Later design settled it past both options, and the settled form is what m7 builds:

• No sidecar undo state, ever. The undo stack reseeds from HEAD's first-parent ancestry on load; redo starts empty. In-session it behaves as classic dual stacks; after relaunch, past restore commits reappear as ordinary undoable steps (06-history-undo.md ▸ Rules). Nothing is stored beside the repo, so nothing can drift from it.
• The board-wide history browser / timeline is explicitly out of scope — it is a tracker-integration-era feature (07-sync-collab.md's deferred story), not part of the git milestone. The commit trail remains its natural substrate whenever it happens; the forward-restore model is all the preparation it needs.
• The one deliberate carve-in: the card window's read-only per-card History section (05-card-window.md) — a scoped log view, not a browser. Per-row restore and lane history stay on the wishlist.

What did not carry over

Three of the source's leanings were settled differently by 06/07; they are recorded here so this doc cannot be read as endorsing them:

• C1, the undo substrate: the source leaned toward a hybrid — model-layer inverse operations for ⌘Z, with git as a recorder. Settled differently: on git boards the commit trail itself is the substrate — the stack is HEAD's first-parent ancestry, and undo applies forward restore commits (06-history-undo.md). Inverse operations exist, but as the free tier's native undo substrate (13-native-undo.md) behind the same HistoryProviding seam — a tier seam, not a hybrid inside one system.
• A1, iCloud coexistence: the source's lean (via the pathfinder wishlist) was dual mode per document — cloud-synced boards silently get no git. Settled differently: iCloud Drive is not supported at all — no accommodations, a thorough once-per-board warning that recommends local disk plus git remote, and no hard block (07-sync-collab.md ▸ iCloud Drive). Mode is decided by .git presence alone, never by the board's location.
• B6, sync cadence as the divergence budget: the source framed cadence as the decision that determines how good a silent merge engine must be. Settled differently: there is no merge engine — auto-commit keeps the tree clean by pull time, pull rebases with local-wins on conflicting hunks, and rejected pushes fetch-rebase-push automatically, so conflicts are structurally impossible rather than managed (07-sync-collab.md). Cadence survives only as 06's history-legibility constraint (a shared board's log must stay bearable), not as a divergence budget.

Already absorbed — pointers, not restatements

The rest of the source's conclusions that motivated 06/07 live there in settled form; cite those docs, not this one: repo maintenance and growth posture (A2 → 06 ▸ Repository hygiene), the commit-failure taxonomy and lock handling (A3 → 06 ▸ Interaction with external writers), the repo-state gate for foreign states (A4 → 06 ▸ Rules ▸ Abnormal repo states), auth and transport limits (B5 → 07 ▸ Remote authentication), history as a read surface and per-mutation semantic messages (B8, C2, and the source's strongest cross-cutting signal → 06 ▸ Commit messages), undo scope and focus routing (C6 → 06 ▸ Undo routing), and the connect-time privacy sentence (B9 → owed by the remote-setup surface; 07 ▸ Mode: git).

Open questions

None — this doc extracts settled material only. The source file's eight "open decisions" are all closed: 1 (A1), 3 (B6), 4 (C1) as recorded above; 2 (A4), 5 (C2/B8), 6 (C4), 7 (C5) in 06-history-undo.md's Rules and Commit messages; 8 (C8) as recorded above.