diff --git a/DESIGN/06-history-undo.md b/DESIGN/06-history-undo.md index 2a06f6c..ea601d7 100644 --- a/DESIGN/06-history-undo.md +++ b/DESIGN/06-history-undo.md @@ -79,7 +79,7 @@ Agent and hand edits arrive through the watcher like any change and get auto-com - **Commit granularity resettled to Edit sessions**: body commits land at the Edit→Preview flip (the effective Save button), not at typing-settle; the committer stages around open sessions (Rules ▸ Auto-commit). - **Branch switch gates on explicit save-or-discard** for open Edit sessions instead of silently flushing (Branch switching). - **Commit messages upgraded for external writers**: full schema-1 diff surface, foreign commits in the same vocabulary (no "External edit" prose), semantic launch catch-up, untitled-item rendering (Commit messages). -- The rewrite should extract the old repo's AI-ANALYSIS-git-operations.md conclusions (forward-restore model, C3/C8) into a short normative doc rather than re-deriving them. +- The old repo's AI-ANALYSIS-git-operations.md conclusions (forward-restore model, C3/C8) are extracted into [14-git-operations.md](14-git-operations.md) rather than re-derived — cite it, not the pathfinder file. ## Out of scope diff --git a/DESIGN/14-git-operations.md b/DESIGN/14-git-operations.md new file mode 100644 index 0000000..e084b22 --- /dev/null +++ b/DESIGN/14-git-operations.md @@ -0,0 +1,37 @@ +# 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. diff --git a/DESIGN/README.md b/DESIGN/README.md index d039a9f..516460f 100644 --- a/DESIGN/README.md +++ b/DESIGN/README.md @@ -26,6 +26,7 @@ Each document covers one aspect of the design. Within each: | [11-command-nexus.md](11-command-nexus.md) | The command Nexus — every command and action: bindings, contexts, customizability | | [12-editions.md](12-editions.md) | The tiers (free / Pro subscription / Teams deferred): one-app distribution, entitlement, provider seam, feature matrix | | [13-native-undo.md](13-native-undo.md) | macOS-native undo/redo — the free tier's history substrate | +| [14-git-operations.md](14-git-operations.md) | Extracted pathfinder git-operations conclusions: the forward-restore model — **Pro tier** | ## Deferred design iterations